Nhận xét lớp php

Question

Một thẻ đã tồn tại với tên chi nhánh được cung cấp. Nhiều lệnh Git chấp nhận cả tên thẻ và tên nhánh, vì vậy việc tạo nhánh này có thể gây ra hành vi không mong muốn. Bạn có chắc chắn muốn tạo nhánh này không?

Nội dung chính Show

1. Viết mã giải thích chính nó
2. Giữ cân bằng
3. Ghi nhớ về các khối tài liệu
Tóm lược
Chia sẻ bài viết này
Làm thế nào để bình luận trong mã PHP?
Làm cách nào để nhận xét nhiều dòng trong PHP?
Làm thế nào để viết PHPDoc?
Lớp học PHP là gì?

Khá nhiều nhà phát triển PHP viết nhận xét cùng với mã 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 bình luận để giữ cho chúng hữu ích?

1. Viết mã giải thích chính nó

Đầu tiên và quan trọng nhất, mã bạn viết có thể đóng vai trò là một phần 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 logic thành các đoạn mã, bạn có thể làm rất nhiều việc để làm cho mã rõ ràng. Đây chỉ la một vai vi dụ

Đặt tên biến, hàm và lớp
Vì bạn có thể đặt tên cho các đoạn mã của mình theo bất kỳ cách nào bạn muốn, nên bạn có thể sử dụng nó làm lợi thế của mình trong việc giữ cho mã 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 kỳ 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 lớp

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;
        }
?>

1, chỉ cần gọi nó là

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;
        }
?>

2, không phải là

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;
        }
?>

3,

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;
        }
?>

4 hoặc

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;
        }
?>

5. Đừng sợ mắc lỗi chính tả trong các 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 được sử dụng hoặc các điểm không nhất quán khác trong mã 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 ra điều gì đang xảy ra trong mã 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.

Gợi ý loại
PHP cho phép bạn đặt tên lớp/giao diện hoặc từ khóa

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;
        }
?>

6 /

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.");
    }

    //...
}
?>

0 bên cạnh tham số chức năng. Nó ngăn bạn thực hiện các lệnh gọi sai chức năng nhưng nó cũng đóng vai trò là một phần thông tin quan trọng cho bất kỳ ai đọc mã 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 xem các hàm và lớp khác nhau có thể truyền giá trị cho nhau như thế nào. Và hãy nhớ rằng IDE của bạn có thể sẽ giải thích 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
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. Gán khả năng hiển thị thích 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 mã hướng đối tượng chất lượng. Một mặt, nó cho biết mã nào đại diện cho phần logic nên ở bên trong lớp và không được tiết lộ cho các lớp khác trong ứng dụng. Mặt khác, nó hiển thị 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 mã bao gồm cài đặt khả năng 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 số phương thức công khai mà họ có thể tham khảo trong mã của mình. Họ cũng sẽ nhận thấy những phần nào của logic mà bạn đã viết sẽ được xử lý bởi các phương thức của lớp riêng và có lẽ không nên đụng đến

Một lần nữa, những gợi ý như vậy cũng đang được diễn giải bởi IDE của bạn. Trình chỉnh sửa bạn sử dụng có thể hiển thị cho bạn danh sách các phương thức của 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à để ý các biểu tượng khóa bên cạnh tên phương thức

2. Giữ cân bằng

Tất nhiên, bạn có thể cảm thấy rằng mã 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 triển khai 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ư 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 bạn biết được chuyện gì đang xảy ra.

Mặt khác, các khối nhận xét không nên bù đắp cho mã được viết kém. Nếu mã 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 nếu không phân tích nó trong vài phút, thì để nó như vậy 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 nỗ lực tái cấu trúc mã thay vì cố gắng giải thích nó trong nhận xét

Ngoài các khối mã phức tạp, cũng có những phần mã 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 trong ứng dụng của họ, theo tôi, điều này là không cần thiết. Để 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 mã của bạn thường là nhà phát triển (hoặc ít nhất là tôi cho là vậy), vì vậy anh ấy/cô ấy sẽ có thể nhận ra rằng thuộc tính

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.");
    }

    //...
}
?>

1 của lớp

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.");
    }

    //...
}
?>

2 đại diện cho chủ sở hữu ký gửi. Đó là lý do tại sao tôi nghĩ rằng việc đưa thêm nhận xét vào những phần như vậy của mã thậm chí có thể khiến nó khó đọc hơn thay vì giúp người đọc theo bất kỳ cách nào

Nhận xét cũng thường không cần thiết trong các phần đơn giản khác của 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 tạo, 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 rằng bạn có thể dễ dàng tìm ra điều gì đang xảy ra trong phần mã được trình bày ở trên. Nhưng nếu bạn muốn bình luận mã, nó có thể sẽ giố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.");
    }

    //...
}

?>

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

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.");
    }

    //...
}
?>

3. Tôi đã sử dụng

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.");
    }

    //...
}
?>

4 để mô tả loại thuộc tính của lớp và

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.");
    }

    //...
}
?>

5 để thông báo về loại tham số phương thức. Bạn cũng có thể sử dụng thẻ

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.");
    }

    //...
}
?>

6 để thông báo về loại giá trị được hàm trả về. 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 một phần của ứng dụng (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 do Moshe Teutsch viết

Thẻ khối tài liệu chứa thông tin không thể đưa vào chính mã. Việc chỉ định loại thuộc tính lớp hoặc giá trị trả về của hàm đặc biệt hữu ích vì nó có thể được phân tích cú pháp bởi hầu hết các IDE và được hiển thị trong gợi ý. Tất nhiên, bạn cũng có thể chèn một văn bản tùy chỉnh vào khối tài liệu sẽ đóng vai trò là tài liệu về 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 của nó từ bên ngoài mã. 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 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 bài viết Tạo tài liệu với ApiGen của Bruno Skvorc để tìm hiểu thêm về cách tiếp cận như vậy

Nếu mã dễ hiểu và tôi không cần tạo tài liệu mở rộng, tôi chỉ cần 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à mã không quá phức tạp

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;
        }
?>

0

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 mã rõ ràng và chỉ giải thích chính nó. Vị trí thích hợp để đặt nhận xét là khi bạn thực hiện một số logic phức tạp hoặc sử dụng các lệnh mà con người không thể đọc được. Bạn cũng nên nhớ chèn các thẻ khối tài liệu mô tả các loại biến hoặc giá trị trả về của hàm vì thông tin đó không thể được đưa vào chính mã. Nếu bạn cần duy trì tài liệu dự án chi tiết hơn, hãy đặt các mô tả thích hợp vào các khối tài liệu

Vui lòng đưa ra nhận xét của bạn về các điểm được trình bày trong bài viết hoặc liên hệ với tôi qua Google+. Nếu bạn có ý kiến khác hoặc sử dụng các quy tắc khác trong công việc của mình, hãy cho chúng tôi biết về điều đó

Chia sẻ bài viết này

Jacek Barecki

Jacek là nhà phát triển web chuyên xây dựng các ứng dụng web mở rộng, chủ yếu là các giải pháp thương mại điện tử. Các công nghệ anh ấy sử dụng hàng ngày bao gồm PHP, MySQL, HTML+CSS và JS+jQuery. Trong vài năm qua, anh ấy là nhà phát triển chính của nền tảng cửa hàng trực tuyến được tùy chỉnh cao ở Ba Lan. Giờ đây, anh ấy đang phát triển một số trang web thương mại điện tử đang chạy ở Ba Lan và Đức, thường có hàng trăm nghìn lượt xem trang mỗi ngày. Để tạm dừng việc viết mã, anh ấy thực hiện các bài tập luyện crossfit đầy thử thách, ra ngoài nếm thử một số món ăn mới hoặc tìm hiểu một cuốn sách hoặc tạp chí tâm lý thú vị

Làm thế nào để bình luận trong mã PHP?

Nhận xét PHP một dòng . Tất cả văn bản ở bên phải của // sẽ bị bỏ qua. Bạn cũng có thể sử dụng ký hiệu băm (#) thay vì // để tạo nhận xét một dòng. type two forward slashes (//) followed by your comment text. All text to the right of the // will be ignored. You can also use a hash symbol (#) instead of // to make a single-line comment.

Làm cách nào để nhận xét nhiều dòng trong PHP?

Trong PHP, chúng ta cũng có thể comment nhiều dòng. Để làm như vậy, chúng ta cần đặt tất cả các dòng trong /* */ .

Làm thế nào để viết PHPDoc?

Tạo khối PHPDoc cho cấu trúc mã .

Đặt dấu mũ trước cấu trúc mã được yêu cầu (lớp, phương thức, chức năng, v.v.), nhập nhận xét khối mở /** và nhấn Enter

Trong menu ngữ cảnh của trình soạn thảo, chọn Tạo. Tạo khối PHPDoc và chọn cấu trúc mã để tạo nhận xét PHPDoc cho

Lớp học PHP là gì?

Lớp là kiểu dữ liệu do lập trình viên định nghĩa, bao gồm các phương thức cục bộ và biến cục bộ . Lớp là tập hợp các đối tượng. Đối tượng có thuộc tính và hành vi.

programming php

Nhận xét lớp php

1. Viết mã giải thích chính nó

2. Giữ cân bằng

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

Tóm lược

Chia sẻ bài viết này

Làm thế nào để bình luận trong mã PHP?

Làm cách nào để nhận xét nhiều dòng trong PHP?

Làm thế nào để viết PHPDoc?

Lớp học PHP là gì?

Bài Viết Liên Quan

Quảng Cáo

Có thể bạn quan tâm

Toplist được quan tâm

Quảng cáo

Xem Nhiều

Quảng cáo

Chúng tôi

Điều khoản

Trợ giúp

Mạng xã hội