Coding Convention

Quy ước viết mã nguồn trong bogoengine

Về định dạng mã

• Để 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[]).

• 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.

• 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ụ:

  bglen_t bgstrLen (bgstr str) {
      bglen_t res = 0;
      bglen_t pos = 0;
      bglen_t byteNum = strlen (str);
  
      while (pos < byteNum) {
          res++;
          pos += bgcharLen (str + pos);
      }
  
      return res;
  }

• 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ự.

Về phong cách viết mã và ngữ nghĩa

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

• 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. Quy ước viết test được nêu rõ tại [đây](https://github.com/cmpitg/bogoengine/wiki/Viết test).

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

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

• Không thao tác trên char. Ngoại trừ trường hợp thực sự bắt buộc, tất cả các thao tác đều thực hiện với bgstr, sử dụng các hàm cung cấp trong utf8small.h.

• 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 sử dụng làm shortcut 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, 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 và nên rõ ngữ nghĩa nhất có thể. Các hàm thuộc bogoengine nên dùng quy ước viết tắt string thành str. Các hàm sử dụng bogoengine không nên viết tắt.

• Nếu hàm trả lại giá trị bool, tên hàm cần chia ở ngôi thứ ba số ít và trả lại kiểu bgbool (thực chất là type alias của char).

• Nếu hàm trả lại một string, luôn luôn đặt tên hàm với dạng:

  void functionWithReturnValue (source, target);
  void functionWithReturnValue2 (source, target, arg1, arg2, arg3, ...);
  void functionInAssigningForm (target, source);

  Trong đó source là tham số chính truyền vào, target là kết quả (string) trả lại. Các args tương ứng là các tham số phụ khác. Hàm phải đảm bảo source không bị thay đổi (immutable) khi ra khỏi hàm, nghĩa là chương trình vẫn chạy đúng khi target == source. Để làm được điều hày, source cần được clone (sử dụng bgstrDup chẳng hạn), đem đi xử lý, và trả lại target nếu cần.