[Coding Convention] PSR và Coding Standard in Framgia

Bài đăng này đã không được cập nhật trong 6 năm

Coding conventions

Coding conventions là tập hợp những nguyên tắc chung khi lập trình nhằm làm cho code dễ đọc, dễ hiểu, do đó dễ quản lý, bảo trì hơn. Coding conventions có những cái chung và cái riêng tuỳ ngôn ngữ, tuỳ cộng đồng, nhưng hầu hết được công nhận và đi theo bởi đa số các lập trình viên trên thế giới.

Quy tắc đặt tên (naming convention)

Các cú pháp thông dụng:

Cú pháp lạc đà (camelCase) Ký tự đầu tiên của từ đầu tiên viết thường những ký tự đầu tiên của những từ tiếp theo được viết hoa. Ví dụ: productPrice, camelCasing, thisIsTheNameThatFollowTheCamelCase
Cú pháp Pascal (PascalCase) Cú pháp Pascal viết hoa chữ cái đầu tiên của mỗi từ. Ví dụ: ProductName, PascalCasing, ThisIsTheNameThatFollowThePascalCase
Cú pháp con rắn (snake_case) Với pháp con rắn, tất cả các chữ cái đều viết thường, và các từ cách nhau bởi dấu gạch dưới. Ví dụ: user_name, this_is_the_name_that_follow_the_snake_case

Việc sử dụng cú pháp nào là tuỳ vào mỗi ngôn ngữ, mỗi cộng đồng định nghĩa, nhưng chung quy đều dùng ba cú pháp này, và kèm theo các nguyên tắc:

Tên lớp thì đặ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, vd: CLICK_COUNTER
Tên biến, tên lớp thường là danh từ, cụm danh từ hoặc tính từ: UserModel, userName, downloadCounter, isDownloaded
Tên hàm thường bắt đầu bằng động từ: getUserName, setUserModel, increaseDownloadCounter
Tên thì phải có nghĩa, KHÔNG ĐƯỢC đặt tên kiểu viết tắt (dlCounter, uName, idl, a, a1, doFA)
Tránh đặt những tên quá chung chung, tối nghĩa: top, best, doIncrease, getAll

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

Bob Martin phát biểu trong cuốn Clean Code: “if small is good, then smaller must be better”.

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 phải giữ ở một giới hạn nhất định nào đó, và nên giữ càng ít càng tốt, ví dụ:

Hàm không nên quá 30 dòng (Martin Lippert-rule 30)
Lớp không nên vượt quá 500 dòng (Clean Code)
Một hàm không được vượt quá 5 tham số, nên giữ <=3 (Clean Code)
Một hàm chỉ làm duy nhất 1 việc, trong trường hợp chính đáng, làm 2 việc cũng được phép, tuy nhiên tên hàm phải nói rõ điều này, vd: increaseDownloadCounterAndSaveToDatabase
Khi khai báo biến, một dòng chỉ chứa một biến
Một dòng không nên dài quá 80 ký tự (Oracle)
Các câu lệnh lồng nhau tối đa 4 cấp

Quy tắc xuống hàng

Theo Oracle

Nếu có dấu phẩy thì xuống hàng sau dấu phẩy ,
Xuống hàng trước toán tử + -…
Nếu có nhiều cấp lồng nhau, thì xuống hàng theo từng cấp
Dòng xuống hàng mới thì nên bắt đầu ở cùng cột với đoạn lệnh cùng cấp ở trên.

Comment

Hạn chế dùng comment để giải thích code, thay vào đó hãy cải thiện đoạn code. Chỉ nên dùng comment trong trường hợp viết documentation cho thư viện, thông tin đính kèm cho class…

Chuẩn viết code trong PHP

Nếu bạn là một lập trình viên thì chắc chắn bạn sẽ nghe nói về mã sạch, về coding convention. Ở bất kỳ một ngôn ngữ lập trình nào cũng đều có quy tắc viết code của riêng nó, và ở PHP chúng ta có một chuẩn viết code có tên là PSR. Vậy PSR là gì và nó như thế nào thì trong bài viết này mình sẽ giúp bạn có một cái nhìn tổng quan nhất trong thời lượng ngắn nhất (mình tiết kiệm thời gian viết còn các bạn tiết kiệm thời gian đọc). PSR là viết tắt của từ PHP Standards Recommendation. Tại thời điểm viết bài thì có 7 chuẩn từ PSR-1 đến PSR-7 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 các lập trình viên và kiến trúc sư nổi tiếng của các framework như CakePHP, Drupal, Joomla…

Vì nội dung chi tiết của từng chuẩn khá là dài, mình chỉ tóm lược những cái gọi là tổng quan nhất còn những cái mà ngôn ngữ nào cũng giống nhau hoặc quá hiển nhiên rồi thì mình xin phép lược bỏ, kể cả những chuẩn của PHP 5.2 trở xuống cũng bị loại bỏ.

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

Những mô tả dưới đây là bắt buộc phải tuân theo:

Một namespace và class đầy đủ điều kiện (fully qualified) 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"), tạm gọi là namespace gốc
Mỗi namespace có thể có nhiều sub-namespace (namespace con)
Từ PHP 5.3 khi khai báo class bạn BUỘC PHẢI khai báo namespace

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

Đây là các chuẩn dùng để viết code, có một vài quy tắc đơn giản dễ hiểu dễ nhớ như sau. Thậm chí đọc xong các bạn sẽ thấy nó hiển nhiên vì lâu nay mình vẫn áp dụng mà giờ mới biết tên của nó là gì?

Code phải được viết trong cặp thẻ <?php ?> và nên sử dụng cặp thẻ ngắn <?= ?> thay cho echo
Code chỉ được sử dụng UTF-8 không có 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 được biết với cái tên khác là StudlyCaps
Các hẳng số phải viết hoa tất cả và phân cách nhau bằng dấu gạch chân
Tên phương thức viết theo quy tắc camelCase
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)

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 PHPStorm để khi ấn tab nó tương đương với việc thụt vào 4 spaces)
Các kí tự 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ự, ko 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ở & đó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ì có thể dùng dấu nháy kép để bọc bên ngoài
Dùng dấu . để nối chuỗi, chú ý rằng trước & 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ự như sau
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