Giới thiệu
Khá nhiều nhà phát triển PHP viết comments cùng với code thực tế. Nhưng bản thân ngôn ngữ không áp đặt bất kỳ quy tắc nào về cách làm như vậy. Bạn chỉ cần bọc chúng xung quanh một số thẻ cụ thể và sau đó bạn có thể viết bất kỳ nội dung nào bạn muốn. Vì vậy, chính xác những gì nên được đặt trong các khối comments để giữ cho chúng hữu ích? Những phần nào của code nên được ghi lại và phần nào không nên? Trong bài viết này tôi sẽ trình bày một số quy tắc quan trọng có thể giúp bạn giữ cho code PHP của bạn được ghi chép tốt và dễ hiểu.
1. Viết code giải thích chính nó
Đầu tiên và quan trọng nhất, code bạn viết có thể đóng vai trò là một tài liệu tốt ngay cả khi không thêm một khối nhận xét nào vào đó. Trong khi chuyển đổi logic thành các đoạn code, bạn có thể làm rất nhiều để làm cho code rõ ràng. Sau đây chỉ là một vài ví dụ:
Đặt tên biến, hàm và lớp
Vì bạn có thể đặt tên cho các đoạn code của mình theo hầu hết mọi cách bạn muốn, bạn có thể sử dụng nó làm lợi thế của mình trong việc giữ cho code dễ hiểu. Chỉ cần nhớ chọn tên rõ ràng, không tạo ra bất kỳ chữ viết tắt lạ hoặc sử dụng tên có thể mơ hồ. Nếu biến của bạn đại diện cho một thể hiện của một VeryImportantCustomer class, chỉ cần gọi nó $veryImportantCustomer, không $customer, $vimpCust hoặc $tempcustomer. Đừng sợ mắc lỗi chính tả trong tên dài hơn vì IDE của bạn có thể sẽ cảnh báo bạn về các biến không sử dụng hoặc sự không nhất quán khác trong code của bạn. Tôi chắc chắn rằng việc sử dụng cách đặt tên phù hợp sẽ giúp ích rất nhiều trong việc tìm hiểu những gì đang diễn ra trong code của bạn. Đó là một quy tắc đơn giản nhưng nó có thể dễ dàng bị lãng quên trong công việc hàng ngày của bạn.
Nhập gợi ý [Type hinting]
PHP cho phép bạn đặt tên class / interface hoặc array/ callable từ khóa bên cạnh một tham số hàm. Nó ngăn bạn thực hiện các cuộc gọi chức năng sai nhưng nó cũng đóng vai trò là một thông tin quan trọng cho bất kỳ ai đọc code của bạn. Bạn không cần phải kiểm tra thân hàm để biết cách gọi hàm. Bạn cũng có thể nhanh chóng kiểm tra làm thế nào các hàm và lớp khác nhau có thể truyền các giá trị giữa nhau. Và hãy nhớ rằng IDE của bạn có thể sẽ diễn giải các gợi ý loại và sử dụng chúng để mô tả các chức năng trong cửa sổ bật lên hoặc gợi ý đang được hiển thị trong khi bạn đang làm việc.
Khả năng hiển thị của phương thức [Method visibility]
Một khái niệm khác đáng nói đến là khả năng hiển thị của phương thức . Việc chỉ định mức độ hiển thị phù hợp cho các phương thức lớp được cho là một phần quan trọng trong việc viết code hướng đối tượng chất lượng. Một mặt, nó cho thấy code nào đại diện cho phần logic nên ở trong lớp và không nên tiết lộ cho các lớp khác trong ứng dụng. Mặt khác, nó trưng ra các phương thức lớp nhất định để truy cập công khai để chúng có thể được gọi từ bên ngoài lớp và giao tiếp với các phần khác của ứng dụng.
Nếu bạn viết code bao gồm thiết lập mức độ hiển thị phương thức phù hợp, các nhà phát triển khác sẽ nhanh chóng tìm ra cách làm việc với lớp bạn đã phát triển. Họ sẽ thấy rằng có một vài phương thức công khai code họ có thể tham khảo trong code của họ. Họ cũng sẽ nhận thấy những phần logic mà bạn đã viết còn lại sẽ được xử lý bằng các phương thức lớp riêng và có lẽ không nên chạm vào.
Một lần nữa, những gợi ý như vậy cũng đang được IDE của bạn diễn giải. Trình soạn thảo bạn sử dụng có thể hiển thị cho bạn một danh sách các phương thức lớp, cùng với khả năng hiển thị của chúng. Chỉ cần nhìn vào hình ảnh bên dưới và chú ý các biểu tượng khóa bên cạnh tên phương thức:
2. Giữ thăng bằng [Keep the balance]
Tất nhiên bạn có thể cảm thấy rằng bản thân code không phải lúc nào cũng đủ rõ ràng và cần giải thích thêm. Điều này đặc biệt đúng khi bạn đang thực hiện một phần phức tạp của logic nghiệp vụ, thực hiện các phép tính phức tạp hoặc chỉ sử dụng các lệnh khó hiểu ngay từ cái nhìn đầu tiên [như các mẫu biểu thức chính quy, biến đổi mảng, v.v.]. Trong những trường hợp như vậy, viết một bình luận ngắn chắc chắn sẽ giúp ích trong việc tìm hiểu những gì đang diễn ra.
Mặt khác, các khối nhận xét không nên bù cho code được viết kém. Nếu code của bạn chứa quá nhiều vòng lặp hoặc cấu trúc điều khiển và thậm chí bạn không biết nó hoạt động như thế nào mà không phân tích nó trong vài phút, thì việc để nó như thế với một vài dòng nhận xét không phải là giải pháp tốt nhất. Bạn nên đặt một số nỗ lực trong việc tái cấu trúc code thay vì cố gắng giải thích nó trong các bình luận.
Ngoài các khối code phức tạp, cũng có những phần code rõ ràng và không đại diện cho bất kỳ logic phức tạp nào. Một số nhà phát triển có xu hướng đặt các khối nhận xét ngay cả đối với các phần này của ứng dụng của họ, điều này không cần thiết theo quan điểm của tôi. Hãy để tôi chỉ cho bạn một ví dụ:
Hãy nhớ rằng người đọc code của bạn thường là nhà phát triển [hoặc ít nhất là tôi cho là như vậy], vì vậy anh ấy / cô ấy sẽ có thể nhận ra rằng_ownerproperty của Deposit class đại diện cho chủ sở hữu tiền gửi. Đó là lý do tại sao tôi nghĩ rằng việc đưa thêm nhận xét vào các phần như vậy của mã thậm chí có thể làm cho nó ít đọc hơn thay vì giúp người đọc bằng mọi cách.
Nhận xét thường không cần thiết trong các phần đơn giản khác trong mã của bạn, không chỉ trong các định nghĩa thuộc tính lớp hoặc các phương thức điển hình [như hàm constructors, getters hoặc setters]. Chỉ cần xem ví dụ dưới đây: