Giữ code PHP của bạn là một tài liệu tốt

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

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 chỉ là một vài ví dụ:

Đặ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ụ:

<?php
    class Deposit {

        /**
         * The deposit owner.
         *
         * @var string
         */
        private $_owner;

         /**
         * The deposit amount.
         *
         * @var float
         */
        private $_amount;

        /**
         * The date when the deposit was opened.
         *
         * @var DateTime
         */
        private $_dateOpened;

        /**
         * Class constructor.
         *
         */
        public function __construct() {
            //...
        }

        /**
         * Sets the deposit owner.
         *
         * @param string $owner The deposit owner name.
         */
        public function setOwner($owner) {
            $this->_owner = $owner;
        }
?>

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:

<?php

public function showUserDetails() {
    $userId = $this->Session->read('userId');
    $userData = $this->getUserData($userId);
    if(!$user->isActive()) {
        throw new Exception("The user account hasn't been activated.");
    }

    //...
}
?>
Tôi chắc chắn rằng bạn có thể dễ dàng tìm ra những gì đang diễn ra trong phần code được trình bày ở trên. Nhưng nếu bạn muốn bình luận code, nó có thể sẽ trông như thế này:

<?php
/**
 * Shows the details of the user that is currently
 * logged in.
 *
 */
public function showUserDetails() {
    //get the current user from session
    $userId = $this->Session->read('userId');   

    //load the user data from database
    $userData = $this->getUserData($userId);

    //check if the user has an active account
    if(!$user->isActive()) {
        throw new Exception("The user account hasn't been activated.");
    }

    //...
}

?>

Trong thực tế, các ý kiến được thêm vào phương thức chứa gần như các từ được sử dụng trong code. Giống như chúng tôi đã nêu trước đây, việc đặt tên đúng giúp code của bạn dễ hiểu và dễ đọc. Theo tôi, phương thức được hiển thị trong ví dụ trên không cần thêm bất kỳ nhận xét nào vì mọi thứ được mô tả bởi chính code. Tất nhiên, tôi vẫn khuyến khích bạn viết bình luận trong những phần đó của ứng dụng phức tạp hơn và cần giải thích thêm.

3. Ghi nhớ về các khối tài liệu

Như bạn có thể thấy trong các ví dụ code ở trên, một số khối nhận xét chứa các từ khóa cụ thể bắt đầu bằng ký tự @ Tôi đã sử dụng @varđể mô tả loại thuộc tính của lớp và@paramđể thông báo về loại tham số phương thức. Bạn cũng có thể sử dụng @returnthẻ thông báo về loại giá trị được trả về bởi một hàm. Các thẻ khác có thể được sử dụng để mô tả một số thông tin chung về ứng dụng hoặc phần của nó (như tác giả, gói, loại giấy phép). Bạn có thể đọc thêm về các khối tài liệu trong bài viết Giới thiệu về PhpDoc được viết bởi Moshe Teutsch.

Thẻ khối tài liệu chứa thông tin không thể được bao gồm trong chính code. Việc chỉ định loại thuộc tính lớp hoặc giá trị trả về hàm đặc biệt hữu ích vì hầu hết các IDE có thể được phân tích cú pháp và được hiển thị trong các gợi ý. Tất nhiên, bạn cũng có thể chèn một văn bản tùy chỉnh trong một khối tài liệu sẽ phục vụ như một tài liệu hàm hoặc lớp. Nó có thể đặc biệt quan trọng nếu dự án của bạn cần có sẵn tài liệu từ bên ngoài code. Trong những trường hợp như vậy, bạn có thể sử dụng các ứng dụng phân tích các khối tài liệu và tạo tài liệu của toàn bộ ứng dụng dựa trên nội dung của chúng. Đọc tài liệu Generate Documentation with ApiGen để tìm hiểu thêm về cách tiếp cận như vậy.

Nếu code dễ hiểu và tôi không cần phải tạo tài liệu mở rộng, tôi chỉ giữ các thẻ cung cấp thông tin về các loại biến và giá trị trả về. Kết quả là, code không quá phức tạp:

<?php
    class Deposit {

        /**
         * @var string
         */
        private $_owner;

         /**
         * @var float
         */
        private $_amount;

        /**
         * @var DateTime
         */
        private $_dateOpened;

        //...

        /**
         * @param string $owner
         */
        public function setOwner($owner) {
            $this->_owner = $owner;
        }
?>

Tóm lược

Trong bài viết này tôi đã trình bày một số mẹo về cách duy trì tài liệu mã trong ứng dụng PHP. Tôi nghĩ rằng các bình luận không cần thiết nếu bạn tạo ra mã rõ ràng và chỉ giải thích chính nó. Vị trí thích hợp để đặt bình luận là khi bạn triển khai một số logic phức tạp hoặc sử dụng các lệnh không dễ đọc cho con người. Cũng đáng ghi nhớ để chèn các thẻ khối doc mô tả các loại biến hoặc giá trị trả về hàm vì thông tin đó không thể được bao gồm trong chính mã. Nếu bạn cần duy trì tài liệu dự án chi tiết hơn, cũng đặt các mô tả phù hợp trong các khối tài liệu.