Coding Conventions: Bí Quyết Viết Code Sạch, Dễ Bảo Trì và Tối Ưu SEO

Coding conventions (quy ước viết code) là tập hợp các nguyên tắc lập trình chung, giúp code trở nên dễ đọc, dễ hiểu, từ đó dễ dàng quản lý và bảo trì hơn. Hãy hình dung code của bạn như một con người. Bạn sẽ thích làm việc với một người gọn gàng, dễ gần hơn hay một người luộm thuộm và khó hiểu? Câu trả lời có lẽ đã rõ.

Coding conventions có những điểm chung và khác biệt tùy theo ngôn ngữ lập trình và cộng đồng phát triển. Tuy nhiên, phần lớn các lập trình viên trên thế giới đều tuân theo những quy tắc chung này.

Mục Lục

1 Các Cú Pháp Thông Dụng
2 Quy Tắc Về Số Lượng
3 Quy Tắc Xuống Hàng
4 Comment
5 Chuẩn PSR trong PHP
6 Kết Luận

Các Cú Pháp Thông Dụng

2.1 Cú Pháp Lạc Đà (camelCase)

Cú pháp: Chữ cái đầu tiên của từ đầu tiên viết thường, chữ cái đầu tiên của các từ tiếp theo viết hoa.
Ví dụ: productName, productPrice, thisIsTheNameFollowTheCamelCase

2.2 Cú Pháp Pascal (PascalCase)

Cú pháp: Viết hoa chữ cái đầu tiên của mỗi từ.
Ví dụ: ProductName, ProductPrice, ThisIsTheNameFollowThePascalCase

2.3 Cú Pháp Con Rắn (snake_case)

Cú pháp: Tất cả các chữ cái đều viết thường, các từ cách nhau bởi dấu gạch dưới.
Ví dụ: product_name, product_price, this_is_the_name_follow_the_snake_case

Tùy thuộc vào ngôn ngữ lập trình và quy ước của cộng đồng, bạn sẽ lựa chọn cú pháp phù hợp. Ví dụ, trong Python, snake_case thường được sử dụng cho tên biến và hàm, trong khi PascalCase thường được sử dụng cho tên lớp.

Một Số Nguyên Tắc Quan Trọng

– Tên lớp: Đặt theo PascalCase.

– Tên biến, tên hàm: Đặt theo camelCase hoặc snake_case.

– Hằng số: Đặt theo UPPER_CASE. Ví dụ: CLICK_COUNTER.

– Tên biến, tên lớp: Thường là danh từ, cụm danh từ hoặc tính từ. Ví dụ: UserModel, userName, downloadCounter, isDownloaded.

– Tên hàm: Thường bắt đầu bằng động từ. Ví dụ: getUserName, setUserName, increaseDownloadCounter.

– Tên phải có nghĩa, không được đặt tên viết tắt. Ví dụ: Không nên đặt uName, pName, idl, a, a1, doFA.

– Tránh đặt những tên quá chung chung, tối nghĩa. Ví dụ: Không nên đặt top, doIncrease, getAll.

Ví dụ minh họa cách đặt tên biến và hàm theo coding conventions

Quy Tắc Về Số Lượng

Trong cuốn sách “Clean Code” của Robert C. Martin, tác giả nhấn mạnh tầm quan trọng của việc giữ cho code ngắn gọn và dễ hiểu.

Số lượng dòng code trong hàm/lớp, số lượng hàm trong lớp, số lượng lớp trong gói cần được giới hạn ở một mức nhất định, và nên giữ càng ít càng tốt.
Ví dụ:

– Hàm không nên quá 30 dòng.

– Lớp không nên vượt quá 500 dòng (theo “Clean Code”).

– Một hàm không nên vượt quá 4 tham số (nên giữ <= 3).

– Một hàm chỉ nên thực hiện một việc duy nhất. Nếu cần thiết phải thực hiện hai việc, tên hàm phải thể hiện rõ điều này. Ví dụ: increaseDownloadCounterAndSaveToDatabase.

– Khi khai báo biến, mỗi dòng chỉ nên chứa một biến.

– Một dòng không nên dài quá 80 ký tự (theo Oracle).

– Các câu lệnh lồng nhau tối đa 4 cấp.

Quy Tắc Xuống Hàng

Theo Code Conventions của Oracle, việc xuống hàng cần tuân theo một số quy tắc nhất định để đảm bảo tính dễ đọc của code.

– Nếu có dấu “,”, xuống hàng sau dấu “,”.

someMethod(longExpression1, longExpression2, longExpression3,
           longExpression4, longExpression5);
var = someMethod1(longExpression1,
                  someMethod2(longExpression2, longExpression3));

– Xuống hàng trước toán tử + – * /…

longName1 = longName2 * (longName3 + longName4 - longName5)
            + 4 * longname6; // Ưu tiên cách này

longName1 = longName2 * (longName3 + longName4 - longName5) +
            4 * longname6;

– Nếu có nhiều cấp lồng nhau, xuống hàng theo từng cấp.

– Dòng xuống hàng mới bắt đầu ở cùng cột với đoạn lệnh cùng cấp ở trên.

Ví dụ minh họa quy tắc xuống hàng giúp code dễ đọc hơn

Comment

Hạn chế sử dụng comment để giải thích code. Thay vào đó, hãy cố gắng cải thiện code để nó tự giải thích.

Chỉ nên sử dụng comment khi viết tài liệu cho thư viện, cung cấp thông tin đính kèm cho class, …

Chuẩn PSR trong PHP

Ở mỗi ngôn ngữ lập trình sẽ có một quy tắc viết riêng. Trong PHP, có một chuẩn viết code được gọi là PSR (PHP Standards Recommendation).

PSR là viết tắt của PHP Standards Recommendation.

Hiện tại có 5 chuẩn từ PSR-0 đến PSR-4 do các thành viên của nhóm FIG (Framework Interop Group) đề xuất. Nhóm này gồm nhiều lập trình viên nổi tiếng từ các framework như CakePHP, Drupal, Joomla…

Chuẩn PSR-0, PSR-4: Chuẩn Autoloading

Những mô tả sau bắt buộc phải tuân theo:

– Từ PHP 5.3, khi khai báo class bạn BUỘC PHẢI khai báo namespace.

– Một namespace và class đầy đủ điều kiện phải có cấu trúc như sau: <Vendor Name>(<Namespace>)*<Class Name>

– Mỗi namespace phải có một top-level namespace (“Vendor name”), gọi là namespace gốc.

– Mỗi namespace có thể có nhiều sub-namespace (namespace con).

Chuẩn PSR-1: Các Chuẩn Cơ Bản

Đây là các chuẩn dùng để viết code, với một vài quy tắc đơn giản như sau:

– Code phải được viết trong cặp thẻ <?php ?> và nên sử dụng cặp thẻ ngắn = <?php echo ?> thay cho echo.

– Mỗi một file PHP chỉ nên làm 1 nhiệm vụ duy nhất, tránh chồng chéo (gọi là side effect).

– Code chỉ được sử dụng UTF-8 không có BOM (BOM – Byte Order Mark là các chuỗi EF,BB,BF ở đầu file cho phép phần mềm biết đây là 1 file UTF-8).

– Namespace phải tuân theo chuẩn PSR “autoloading” (PSR-0, PSR-4).

– Tên class phải viết theo quy tắc PascalCase (hay còn gọi là StudlyCaps).

– Các hằng số phải viết hoa tất cả các chữ, cách nhau bằng dấu gạch chân.

– Tên phương thức viết theo quy tắc camelCase.

Chuẩn PSR-2: Chuẩn Viết Code

Code phải tuân thủ PSR-1 & PSR-0.
Sử dụng 4 khoảng trắng (spaces) để thụt dòng, tuyệt đối không dùng tab (bạn có thể khai báo trong công cụ lập trình để khi ấn tab nó tương đương với việc thụt vào 4 spaces).
Trên 1 dòng không vượt quá 120 kí tự, tốt nhất nên nhỏ hơn hoặc bằng 80 kí tự, không nên có kí tự trắng ở cuối dòng.
Phải có 1 dòng trắng sau khi khai báo namespace và phải có 1 dòng trắng sau các khai báo use.
Thẻ đóng và mở của 1 hàm {} phải nằm riêng biệt trên một dòng.
Trước thẻ mở và đóng hàm {} thì không được có 1 dòng trắng.
Phải dùng dấu nháy đơn ' để khai báo chuỗi không chứa biến, nếu chuỗi có chứa kí tự ' thì dùng dấu nháy kép để bọc bên ngoài (chúng ta rất hay nhầm lẫn vấn đề này).
Dùng dấu . để nối chuỗi, chú ý trước và sau dấu chấm . phải có khoảng trắng. Nếu chuỗi quá dài thì tách làm nhiều dòng và dấu chấm được đặt đầu dòng ngang với dấu bằng.
Các tham số truyền vào hàm phải có 1 dấu cách trước dấu phẩy, bạn có thể tách thành nhiều dòng nhưng phải thụt lề 1 đơn vị.
Đối với khối lệnh switch case thì case phải lùi 4 khoảng trắng so với switch, và các lệnh trong case cũng phải lùi 4 khoảng trắng so với case. Phải có từ khóa break hoặc return, trong trường hợp nào không có thì phải comment //no break
Nếu phải sử dụng abstract và final hay static để khai báo hàm thì bạn phải khai báo theo thứ tự.
Phải có 1 khoảng trắng trước và sau phép toán, khi ép kiểu thì phải có 1 khoảng trắng ngăn cách giữa kiểu dữ liệu và biến được ép kiểu.

Kết Luận

Coding conventions không chỉ giúp code trở nên dễ đọc và dễ bảo trì hơn, mà còn đóng vai trò quan trọng trong việc hợp tác nhóm và đảm bảo tính nhất quán của dự án. Việc tuân thủ các quy ước này là một phần không thể thiếu trong quy trình phát triển phần mềm chuyên nghiệp. Hãy áp dụng những nguyên tắc này để tạo ra những sản phẩm chất lượng và dễ dàng mở rộng trong tương lai.