代码优化 第四期 代码注释规范

注释的理解

注释：对代码的解释。注释不需要运行，它是用来提高代码的可读性和可维护性的。不好的注释会使代码变得更加糟糕，使人更抓狂。

注释的三种类型

• 固定的版权和授权信息，使用一般的星号注释符（/-/）比如下面

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

• 生成用户稳定的注释，使用apidoc要求的格式 /-*/，比如下面

/**
 * @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.
 */

• 代码解释注释，只使用行注释（//）。每行长度限制，和代码块的每行长度限制尽量保持一致。比如：

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

}

注意点：如果一段代码不再需要，一定要记得清理代代码，而不会保留这个注释掉的代码块。

注释产生的问题

看到这个标题可能有人会说 注释能产生什么问题，它又不会执行，也不会报错。难道它还能影响程序吗？没有错，之前我也是这么认为的，后来经过我多年的开发代码，我发现注释有时候确实会成为我们对业务熟悉道路的拦路虎。我们来看看下面的例子：

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

我们发现这个方法的命名改了，但是注释没有改动，这就造成了注释与实现不符的情况发生。所以这也是注释的其中一个问题，需要维护，这样开发人员才能准确知道业务。

注释三原则

• 准确：错误的注释比没有注释更糟糕
• 必要：多余的注释浪费阅读者的时间
• 清晰：混乱的注释会把代码搞得更乱
• 维护：不维护的注释使代码可读性差

准确：

比如当我们在说编程语言的时候，就不能省略“编程”两字，否则就会被误会成平时说的语言

// 注释不准确
public $language = 'php'; // the language 

// 准确
public $language = 'php'; // the programming language

必要：

当代码的变量，方法与类的命名已经能够清晰的表达出自己的语义和逻辑时，那这个时候的注释就会显得多余了。比如下面这俩个反面例子：

	// the programming language （注释不必要）
    public $programingLanguage = 'php';
 	
 	/**
     * Default constructor (注释不必要)
     */
    public function MyClass()
    {
        
    }

清晰

注释和代码需要从视觉上进行分割，要不然就会破坏代码的可读性。比如：

   /* dump debug information
   if (Config::Debug == true) {
       var_dump("Programming language: Java");
   } */
   
   $programingLanguage = "Java";
	
	// 改进注释 将它们分隔开
	// dump debug information
    // if (Config::Debug == true) {
    //   var_dump("Programming language: Java");
   	// }
   
   $programingLanguage = "Java";

	// 正面案例 （不需要注释）
	$programingLanguage = "Java";

维护

注释与业务处理需要同时更新维护。并且不要在代码标注你想要做的工作和已经做过的工作，比如使用TODO，这样就难以维护了。示例如下：

	/*
     * 2021/11/10: add weixin payment method
     * 2021/11/11: add Alipay payment method
     */
	switch ($payMethod) {
            case 'weixin':
                ...
                break;
            case 'Alipay':
                ...
                break;
        }
// 上面的注释，会跟着支付方式的增加而不断增加，那注释也要不断维护了。所以这个时候，
// 推荐是可以不要注释的，因为可读性已经很高了，一眼可以看出这段想表达什么。

ps：注释最好使用英文，因为英文注释的风格会比较大众，团队协作会比较方便。

总结

注释是用来提高代码的可读性和可维护性的。不要让注释偏离了这个原则，破坏了代码的逻辑和可读性。