Understanding of notes

Note: explanation of the code. Comments do not need to be run. They are used to improve the readability and maintainability of the code. Bad comments can make the code worse and make people more crazy.

Three types of comments

• ① For fixed copyright and licensing information, use the general asterisk annotation (/ - /), such as the following

/*
 * Copyright (c) 2021, FirstName LastName. All rights reserved. 
 */

• ② Generate user stable comments, using the format / - * /, as required by apidoc, such as the following

/**
 * @api {get} /user/:id Request User information
 * @apiName GetUser
 * @apiGroup User
 *
 * @apiParam {Number} id Users unique ID.
 *
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

• ③ Code interpretation comments, using only line comments (/ /). The length limit of each line shall be consistent with the length limit of each line of the code block as far as possible. For example:

// Get the primary key value for a save query.
public function getKeyForSaveQuery()
{

}

Note: if a piece of code is no longer needed, be sure to clean up the generation code without retaining the commented out code block.

Problems caused by comments

When you see this title, someone may say that the annotation can cause any problems, and it will not execute or report errors. Can it still affect the program? No mistake. I thought so before. Later, after many years of code development, I found that annotations sometimes become a stumbling block for us to get familiar with the business. Let's take a look at the following example:

    /**
     * Get the primary key value for a save query.
     *
     * @return mixed
     */
    protected function getSaveQuery()
    {
      
    }

We found that the name of this method has been changed, but the annotation has not been changed, which leads to the inconsistency between the annotation and the implementation. Therefore, this is also one of the problems of annotation, which needs to be maintained so that developers can accurately know the business.

Note three principles

• Accuracy: incorrect comments are worse than no comments
• Necessary: unnecessary notes waste the reader's time
• Clarity: confusing comments will mess up the code
• Maintenance: comments that are not maintained make the code less readable

Accuracy:

For example, when we speak a programming language, we can't omit the word "programming", otherwise we will be misunderstood as a language spoken in ordinary times

// Inaccurate comments
public $language = 'php'; // the language 

// accuracy
public $language = 'php'; // the programming language

Necessary:

When the naming of variables, methods and classes in the code can clearly express their semantics and logic, the comments at this time will be redundant. For example, the following two negative examples:

	// the programming language
    public $programingLanguage = 'php';
 	
 	/**
     * Default constructor (Notes (unnecessary)
     */
    public function MyClass()
    {
        
    }

clear

Comments and code need to be visually separated, otherwise it will destroy the readability of the code. For example:

   /* dump debug information
   if (Config::Debug == true) {
       var_dump("Programming language: Java");
   } */
   
   $programingLanguage = "Java";
	
	// Improve notes to separate them
	// dump debug information
    // if (Config::Debug == true) {
    //   var_dump("Programming language: Java");
   	// }
   
   $programingLanguage = "Java";

	// Positive case (no notes required)
	$programingLanguage = "Java";

maintain

Comments and business processing need to be updated and maintained at the same time. And don't mark the work you want to do and the work you have done in the code, such as using TODO, which is difficult to maintain. Examples are as follows:

	/*
     * 2021/11/10: add weixin payment method
     * 2021/11/11: add Alipay payment method
     */
	switch ($payMethod) {
            case 'weixin':
                ...
                break;
            case 'Alipay':
                ...
                break;
        }
// The above notes will increase with the increase of payment methods, and the notes should be maintained continuously. So at this time,
// It is recommended not to comment, because the readability is already very high. You can see what this paragraph wants to express at a glance.

ps: It is best to use English for annotation, because the style of English annotation will be more popular and team cooperation will be more convenient.

summary

Comments are used to improve the readability and maintainability of code. Don't let comments deviate from this principle and destroy the logic and readability of the code.