Code Convention là gì? Tổng hợp các quy tắc cần biết khi viết code

Tóm lược nội dung

 

• Khái niệm Code Convention: Giúp đảm bảo sự đồng nhất, rõ ràng và dễ bảo trì trong dự án.

 

• Lợi ích: Tăng khả năng đọc hiểu mã, giảm chi phí và thời gian bảo trì.

 

• Các quy tắc cơ bản: Bao gồm cách đặt tên, tổ chức dòng code, quy tắc comment và giới hạn độ dài mã nguồn.

 

• Chuẩn PHP: Nắm vững PSR-1 và PSR-2 để viết code PHP chuyên nghiệp và nhất quán.

 

1. Code Convention là gì?

 

Code Convention là tập hợp những nguyên tắc được thống nhất trong quá trình phát triển phần mềm, hướng dẫn cách viết mã nguồn – từ cách đặt tên, định dạng, bố cục đến cách viết comment.
Nhờ tuân thủ các quy ước này, lập trình viên có thể tạo ra những đoạn code dễ hiểu, hạn chế lỗi và thuận tiện hơn trong việc bảo trì.

 

 

Các tiêu chuẩn lập trình thường được cộng đồng hoặc tổ chức xây dựng để duy trì tính nhất quán. Ví dụ:

 

• Ngôn ngữ C sử dụng tiêu chuẩn K&R.

 

• C# có bộ quy tắc riêng của Microsoft.

 

• Java tuân theo hướng dẫn mã hóa của Oracle.

 

Một bộ code convention thông thường sẽ quy định:

 

• Cách đặt tên biến và hàm (camelCase, snake_case, PascalCase, …).

 

• Kiểu thụt lề, độ rộng, sử dụng tab hay space.

 

• Quy tắc đặt dấu ngoặc nhọn.

 

• Khoảng trắng trong biểu thức.

 

• Cách viết comment.

 

• Đặt tên class, file, phương thức.

 

• Quy định về cấu trúc và tổ chức tệp tin.

 

2. Lý do cần áp dụng Coding Convention

 

Theo nhiều nghiên cứu, từ 40% đến 80% chi phí phần mềm thường dành cho việc bảo trì mã nguồn. Khi code được viết theo chuẩn, việc đọc, hiểu và chỉnh sửa trở nên dễ dàng hơn, giúp tiết kiệm đáng kể thời gian và công sức.

 

 

Lợi ích khi tuân thủ quy tắc viết code

 

• Giúp đội ngũ phát triển phối hợp hiệu quả hơn.

 

• Mã nguồn rõ ràng, người khác dễ tiếp nhận và hiểu nhanh ý đồ.

 

• Dễ mở rộng, tái sử dụng và nâng cấp phần mềm.

 

• Hạn chế lỗi phát sinh trong quá trình phát triển.

 

• Tăng tính bảo mật, hiệu năng và độ ổn định của hệ thống.

 

3. Các quy tắc phổ biến trong Code Convention

 

3.1. Nguyên tắc viết code “sạch”

 

• Luôn viết code ngắn gọn, dễ hiểu, tránh phức tạp hóa vấn đề.

 

• Khi chỉnh sửa, hãy để mã nguồn sau cùng rõ ràng và sạch hơn trước.

 

• Tìm hiểu nguyên nhân cốt lõi của lỗi thay vì chỉ khắc phục tạm thời.

 

 

3.2. Quy tắc đặt tên

 

Tên biến, hàm, class hay file có ảnh hưởng lớn đến khả năng đọc hiểu code.
Một hệ thống lớn sẽ rất khó bảo trì nếu các hàm được đặt tên mơ hồ như function1, abc, hoặc temp.

 

Ba kiểu đặt tên thường gặp gồm:

 

• camelCase: Từ đầu viết thường, các từ tiếp theo viết hoa chữ cái đầu. Dùng cho tên biến hoặc hàm.

 

Ví dụ: firstName, getUserInfo(), findMember().

 

• PascalCase: Viết hoa chữ cái đầu của tất cả các từ, thường dùng cho class hoặc đối tượng.

 

Ví dụ: UserProfile, CustomerOrder.

 

• snake_case: Tất cả viết thường, các từ ngăn cách bằng dấu gạch dưới.
  Ví dụ: max_value, get_result().

 

 

Một số lưu ý khi đặt tên

 

• Tên phải phản ánh rõ chức năng hoặc mục đích sử dụng.

 

• Hạn chế viết tắt hoặc dùng tên không rõ nghĩa.

 

• Class, biến nên là danh từ; hàm, phương thức nên bắt đầu bằng động từ.

 

• Tránh dùng “magic number” (các giá trị số viết trực tiếp trong code); nên khai báo hằng số để thay thế.

 

3.3. Quy tắc về số lượng

 

Theo các tài liệu nổi tiếng như Clean Code (Robert C. Martin) và Refactoring in Large Software Projects (Martin Lippert), cùng với khuyến nghị của Oracle, nên tuân thủ các giới hạn sau:

 

• Một dòng code không nên vượt quá 80 ký tự.

 

• Cấu trúc lồng nhau không quá 4 cấp.

 

• Mỗi hàm không nên có hơn 5 tham số và không dài quá 30 dòng.

 

• Mỗi class không nên vượt quá 500 dòng.

 

• Mỗi hàm chỉ nên thực hiện một nhiệm vụ duy nhất. Nếu có hai nhiệm vụ, cần tách riêng hoặc đặt tên thể hiện rõ chức năng.

 

Ví dụ: increaseDownloadCounterAndSaveToDatabase().

 

3.4. Quy tắc xuống dòng

 

Theo hướng dẫn của Oracle:

 

• Với các đoạn code có nhiều cấp lồng nhau, mỗi cấp nên xuống dòng riêng.

 

• Các đoạn cùng cấp cần căn chỉnh thẳng hàng để dễ theo dõi.

 

• Khi sử dụng các toán tử như +, -, *, ?, nên xuống dòng trước toán tử để tăng khả năng đọc hiểu.

 

3.5. Quy tắc viết comment

 

• Không sử dụng comment để mô tả những điều hiển nhiên.

 

• Tránh comment ở vị trí đóng ngoặc hoặc kết thúc khối lệnh.

 

• Xóa hoàn toàn code không còn dùng thay vì giữ lại dưới dạng comment.

 

• Comment nên dùng để cảnh báo hậu quả hoặc giải thích những đoạn logic khó hiểu.

 

4. Tiêu chuẩn mã hóa trong PHP: PSR-0, PSR-1, PSR-2, PSR-4

 

Để đảm bảo tính thống nhất và khả năng mở rộng, cộng đồng PHP đã đưa ra các chuẩn PSR (PHP Standards Recommendation) giúp quy định rõ cách viết và tổ chức mã nguồn, đặc biệt là cơ chế autoloading class.

 

PSR-0 và PSR-4: Cơ chế autoload class

 

Hai chuẩn này mô tả cách PHP tự động nạp các class dựa theo namespace và cấu trúc thư mục.
Kể từ phiên bản 5.3, PHP yêu cầu mọi class phải khai báo namespace tương ứng, giúp dự án dễ quản lý và mở rộng hơn.

 

PSR-1: Chuẩn cơ bản

 

PSR-1 quy định những nguyên tắc nền tảng khi viết code PHP:

 

• Toàn bộ mã phải nằm trong cặp thẻ <?php ... ?>.

 

• Có thể dùng cú pháp ngắn <?= ... ?> thay cho echo.

 

• File nên được lưu dưới dạng UTF-8 không BOM.

 

• Mỗi class cần được định danh trong một namespace rõ ràng, đặt tên theo PascalCase, hằng số viết IN HOA và ngăn cách bằng dấu gạch dưới.

 

• Mỗi tệp PHP chỉ nên đảm nhận một nhiệm vụ cụ thể, tuân theo nguyên tắc Single Responsibility Principle (SRP).

 

PSR-2: Chuẩn trình bày mã nguồn

 

PSR-2 mở rộng từ PSR-1, tập trung vào định dạng và bố cục:

 

• Sử dụng 4 ký tự space để thụt lề, không dùng tab.

 

• Dòng code không vượt quá 80 ký tự, tối đa 120 ký tự.

 

• Không có khoảng trắng ở cuối dòng.

 

• Có một khoảng trắng sau các từ khóa namespace và use.

 

• Dấu ngoặc {} nên mở trên cùng dòng với khai báo, cách một khoảng trắng.

 

• Dùng '...' cho chuỗi không chứa biến, "..." cho chuỗi có biến.

 

• Khi khai báo phương thức, thứ tự nên là abstract, final, rồi static.

 

• Luôn đặt khoảng trắng trước và sau toán tử, và khi ép kiểu, nên có khoảng trắng giữa kiểu và biến.

 

Kết luận

 

Tuân thủ Code Convention không chỉ giúp code đẹp và dễ đọc hơn mà còn là yếu tố nền tảng cho một dự án phần mềm chuyên nghiệp.

Một mã nguồn thống nhất giúp đội ngũ phát triển phối hợp hiệu quả, giảm lỗi, rút ngắn thời gian bảo trì và đảm bảo chất lượng sản phẩm phần mềm trong dài hạn.