Coding Convention

Quy ước chung

• BoGoEngine sử dụng functional programming style, hạn chế tối đa side effect và state.

• Để indent, không dùng tab mà sử dụng 04 dấu cách.

• Ngoại trừ việc gọi constructor, tên hàm được ngăn cách với danh cách tham số bởi 01 dấu cách, khi khai báo hàm cũng như khi gọi hàm. Ví dụ hàm main được khai báo như sau: int main (int argc, const char *argv[]).

• Code block được mở đóng ngoặc {} theo Java style: mở ngoặc cùng dòng với câu lệnh trước, đóng ngoặc dưới câu lệnh cuối cùng 01 dòng, ví dụ:

  void helloWorld (const gchar *names[], guint nNames) {
      for (guint iName = 0; iName < nNames; i++) {
          sayHelloTo (names[i]);
      }
  }

• Ngoại trừ hằng string, tất cả các dòng đều không được phép vượt quá 80 ký tự.

• Mọi hàm xử lý buộc phải có test và documentation giải thích chi tiết, đầy đủ chức năng của hàm cũng như input/output của hàm, trừ khi ngữ nghĩa của hàm được phản ánh quá rõ ràng thông qua cách đặt tên. BoGoEngine sử dụng GoogleTest nên quá trình viết test rất đơn giản và hiệu quả.

• Hạn chế tuyệt đối việc thêm cấu trúc dữ liệu mới.

• Hạn chế tuyệt đối các thao tác cấp phát/thu hồi bộ nhớ bằng tay như: new, delete, delete[], malloc, ...

• Hạn chế tuyệt đối việc mở rộng method cho class/struct. BoGoEngine viết theo functional programming style. Hãy sử dụng hàm và tính năng function overloading thay vì dùng method.

• Các hàm làm việc trên Glib::ustring, sử dụng toStdString để chuyển đổi sang STL String của C++ chuẩn, hoặc toCString để chuyển đổi sang C String.

• Không thao tác trên char, tất cả các thao tác đều thực hiện trên Glib::ustring. Tuy nhiên hàm processKey là trường hợp ngoại lệ.

• Trước và sau mỗi toán tử tồn tại duy nhất một dấu cách.

• Sau dấu mở ngoặc và trước đóng ngoặc không được phép có dấu cách nào.

• Chương trình không đặt thêm bất kỳ một exception nào mà sẽ trả lại unexpected result trong những trường hợp đó. Mời bạn Google để biết lý do. Một lời giải thích ngắn gọn có thể tìm ở đây.

Cách thức đặt tên

• Các hằng primitive được VIẾT_HOA_TOÀN_BỘ_VÀ_NGĂN_CÁCH_BỞI_GẠCH_CHÂN.

• Các macro được đặt tên giống các hằng, đồng thời phải được bắt đầu bởi ít nhất một dấu gạch chân. Tuy nhiên những macro dùng đề viết shorthand cho hàm cần được đặt tên giống quy tắc đặt tên hàm.

• Các hằng non-primitive, tên struct, tên enum, tên class được ViếtHoaCácChữCáiĐầu.

• Tên biến, hàm, method được đặt theo kýPhápCamelBack.

Khi thêm một hàm mới

• Đưa prototype của hàm vào đầu header file tương ứng, sau phần khai báo các kiểu và hằng.

• Khi đưa hàm vào file code tương ứng, đặt hàm ở đầu đoạn code chính.

• Các hàm là overloading của nhau phải được đặt gần nhau.

• Tên hàm đặt theo cú pháp camelBack.

• Nếu hàm tác động lên string, hàm đó cần có signature cho cả 3 kiểu Glib::ustring, std::string, và gchar *, trong đó một implementation là chính, 2 signature còn lại tái sử dụng implementation này. Ví dụ: FIXME.

• Nếu hàm tác động lên char, hàm đó cần có signature cho cả 4 kiểu Glib::ustring, std::string, gchar, và guint, trong đó một implementation là chính, 3 signature còn lại tái sử dụng implementation này.

• Nếu hàm trả lại giá trị bool, tên hàm cần chia ở ngôi thứ ba số ít và kết thúc bởi P (predicate). Ví dụ: containsP, hasWordP, ...