到底如何写好注释呢？来呀，看这里

Posted 2022-02-25 嘴巴吃糖了

专栏介绍

对于程序员而言，相信大家曾经都有这样的经历，要去修改别人的代码，每次接到这样的任务，心里都是有苦说不出呀，于是乎硬着头皮上吧，但是看到没有任何注释，一个函数好几百行的代码时，内心更是趋于崩溃，心想还不如自己重写一遍呢。

之所以出现这样的原因，一方面是因为可能对原有的业务逻辑并不熟悉，另一方面其实更多是因为之前的代码写的太烂啦，业务逻辑不熟悉，我们找产品，找同事对一下，梳理一下就清楚啦，但是太烂的代码会成本的增加我们的工作量，而且修改完以后，内心还是一万个不放心，生怕又改出新的问题。

因此，如何写出更加优雅，更加可维护的代码，就变的十分重要，要想让自己的代码更加优雅和整洁，要从命名，函数，注释，格式等多个方面去养成良好习惯，因此，本专栏 代码整洁之道-理论与实践 就是从命名，函数，注释等多个方面从理论到实战进行总结，希望可以让大家有一个更加清晰的认识。

这里要强调两句话：

1. 我们写代码是给人的，是给我们程序猿自己看的，不是给机器看的，因此，当我们写代码的时候，要经常思考，我们写下的这段代码，别人如果此时看了是否可以比较清晰的理解代码的含义，如果觉得不太好理解，是否意味着我们的代码可以进一步优化呢，是否意味着我们需要加一些注释呢。 总之，都是为了 代码能够让别人也看得懂。
2. 代码写的好不好，和技术能力本身不是成正相关的，也就是说代码要写好，更多的还是要养成良好的习惯，并且从态度层面去重视这个事情，和技术能力本身没有强相关的关系，当然技术能力本身也很重要，它可以加成让我们的代码可以使用更好的设计模式等去组织代码。

该专栏文章目录如下：

1. 【代码整洁之道】命名篇
2. 【代码整洁之道】注释篇
3. 【代码整洁之道】函数篇
4. 【代码整洁之道】格式篇（待发布）
5. 【代码整洁之道】对象和数据结构篇（待发布）
6. 【代码整洁之道】错误处理篇（待发布）
7. 【代码整洁之道】单元测试篇（待发布）
8. 【代码整洁之道】迭代篇（待发布）

说明：该专栏【代码整洁之道 - 理论与实践】未来也会持续围绕代码整洁去展开更多更深入的内容，也欢迎大家点赞和关注哦～😊😊😊

理论篇

相信我们平时的开发中，多多少少都会加一些代码注释，用于去说明对应的代码片段的含义，优雅的注释一定是会有助于代码理解的，但是这里想强调两点：

1. 注释本质上是为了弥补我们直接用代码来表达意图的不明确性，其目的还是服务于代码，因此，我们关注的核心依然是代码，如果能用优雅的代码清晰的表达含义的时候，就没必要再使用注释，同时，我们在写代码的时候，也要尽可能做到用简洁清晰的代码逻辑，而不是用大量的注释来弥补那些糟糕的代码。
2. 注释也是需要专门去维护的，随着需求的不断迭代，注释很可能也是需要不断去更新的，如果不去维护，时间越久，注释的含义与最新代码的含义差的越远，反而引起歧义

总结下来就是：注释，不能美化糟糕的代码，接下来，我们就看看平时开发中可能多多少少会遇到一些好注释和坏注释。

好注释

到底哪些是好注释呢？或者哪些地方需要我们去写注释呢？

法律信息

有时候，公司代码规范要求必须编写与法律相关的注释，例如：版权，著作权等，一般都需要在文件的头部去添加相关法律信息的注释。或者我们平时相关去开源自己相关的一些工具或者库的时候，都可以在文件头部加这样的注释，这也是推荐的。

例如：看一下react的源代码文件中：

公共API的注释

有时候，比如一个方法可能会出现一些晦涩难懂的参数以及返回值等，这时，我们也可以添加注释，去说明各个参数的含义，以及返回值的含义等。例如：lodash源代码中的各个方法：

注意：一般在编写一些工具库或者公共方法的时候，我们一定要把相应的注释都加上，这样其他人在调用你写的这个工具的时候，才能够去更好的理解去怎么使用， 或者我们在项目中，要抽象一个公共的组件的时候，也需要去把各个prop，event的含义去通过注释的方式去阐述清楚。

当然，不止公共方法，如果我们平时业务开发中，如果有些方法逻辑比较复杂，这时，我们要首先想能不能尽可能去优化代码的逻辑，其次再去考虑是否有必要添加一些注释。

TODO注释

通过TODO注释，可以在项目中，把一些暂未实现的功能列表等通过TODO注释的形式来记录一下。

警示作用

开发中，可能有些代码逻辑可能会导致某种后果，这时，我们也需要去添加注释去说明一下，从而对看到这段代码的程序员起到一个警示作用。

其实，不仅仅是警示作用，代码中，任何情况下，如果确认在代码逻辑已经足够好，但是依然需要去说明一下的情况下，我们都可以去通过添加注释的形式，去说明或者强调一下。

坏注释

注释不认真对待

// bad case
// 获取列表
function getTastList() 
  //...

相信我们平时开发中，大多数都会写过上面这种注释，但其实上面的代码犯了两个错误：

1. 多余的注释：上面这个方法getTaskList已经能够通过方法名比较清晰的明白该方法的作用啦，就是获取任务列表。没必要再加注释，注释的作用是为了弥补代码表达的不足，不是每段代码都要加注释，反而是能用代码表达清晰的，就不必再加注释。
2. 误导性注释：既然你选择加注释，那就认真对待注释，加了可以起到效果，不要把注释写的模棱两可，或者可有可无，假如文件中还有一个获取其他列表的方法，那是不是就有歧义啦。

这里只是想强调一下，我们一定要认真对待注释，同时尽可能写的完整和清晰。否则很可能起到反作用。

哪里都加注释

可能团队要求加注释了，于是乎就尽可能的能加注释就全部加了，不管有没有必要，哪里都加，这更是不推荐的，注释的维护也是有成本的，我们反而是应该能用代码表达的就只用代码，尽可能不用注释。

日志式注释

有时候，有些文件可能修改比较频繁，于是会就把所有的修改记录全部添加到注释中，其实也是没有必要的，时间长了，只会越来越冗余。

注释掉的代码

这个大家肯定都做过，某些功能或者代码可能暂时需要隐藏，于是直接把对应的代码注释掉，对于自己来说，可能是更方便啦，但是对于别人啦，当别人看到一段代码注释掉啦，肯定有产生疑问？这段代码是否还有作用，能不能删等？而且注释的代码越多，整体代码质量就会越差。 因此，如果有需要暂时隐藏的功能，我们直接把对应的功能删除即可，其实重新找回来也是很容易的，从git历史版本等可以很轻易的找出来。

非本地注释

也就是说 我们写注释时，一定要确保描述了离它最近的代码，而不是在当前地方描述另外一个地方的代码。

注释信息过多

注释的信息过多，也没人愿意看，不仅代码，注释也要简洁，能够说明问题即可。

总结：以上不管是好注释还是坏注释，都可能是我们平时开发中，可能遇到的，也可能就是自己写的，我们通过这节的学习，至少知道了哪些注释是好的，哪些是坏的，以后，我们要可能避免写出这些还注释。总结起来一句话；能用优雅的代码表达，就不要用注释，如果必须加注释，一定要认真去维护和书写注释。

规范篇

【必须】使用/* … */进行多行注释

// bad case
// getNumber() return a new number
// @param Number number
// @return Number number
function getNumber(number) 
  return number;

​
// good case
/*
* getNumber() return a new number
*/
function getNumber(number) 
  return number;

【必须】 /** ... */ 风格（首行有两个 *）的块级多行注释仅能被用于 JSDoc。

也就是说：我们上面第一点提到的多行注释，首行是使用单* 的，这种方式相当我们可以自定义的格式自由组织注释的内容，但是如果使用首行双*的话，仅能被用于Jsdoc， Jsdoc是什么呢？官网链接如下：JSDoc官网， 简单理解为它就是一个根据javascript文件中注释信息，生成JavaScript应用程序或库、模块的API文档 的工具。后面还会详细讲一下其使用。

// good case
/**
* getNumber() 
* @description: 描述
* @params 类型 参数名 Must
* @params 类型 参数名 Optional
* @returns 类型
*/
function getNumber(number) 
  return number;

拓展：当我们写一些公共工具库或者函数的时候，可以推荐使用该JSDoc，可以帮助我们更规范的生成注释内容。

【推荐】使用//进行单行注释

除此之外，还有两点要注意：

1. 一般将单行注释放在需要被注释的行的上面新行。
2. 建议在注释之前放一个空行，除非它在块的第一行。

注意：通过前面的理论篇的学习，大家再看下面这些代码的时候，很可能产生这样一个疑问：下面好多代码的注释都是无用注释呀，本身命名已经很好的说明其含义啦，没必要再加注释，哈哈哈，是的，你说的非常对，也说明你掌握了对理论篇的内容哈，而下面的case只是从代码规范的角度，看注释放到哪里比较合适，以及注释的格式怎么样比较规范，而注释的具体内容，以及是否需要注释不是本节的关注点。

// bad case
const username = 'kobe'; // username: 用户名
​
// good case 
// username: 用户名 
const username = 'kobe';

// bad case
function getNumber(number) 
  console.log('get number...');
  // 把参数赋值给变量
  const num = number;
  return num;

​
// good case
function getNumber(number) 
  console.log('get number...');
  
  // 把参数赋值给变量
  const num = number;
  return num;

​
// good case
function getNumber(number) 
  // 获取number
  console.log('get number...');
  const num = number;
  return num;

【必须】使用一个空格开始所有的注释，不管是单行还是多行。

// bad case
//username: 用户名
const username = 'kobe'; 
​
// good case
// username: 用户名
const username = 'kobe'; 

// bad case
/*
*getNumber() return a new number
*@params Number number
*@return Number number
*/
function getNumber(number) 
  return number;

​
// good case
/*
* getNumber() return a new number
* @params Number number
* @return Number number
*/
function getNumber(number) 
  return number;

【推荐】使用 // FIXME: 注释当前存在的问题

即如果发现代码中有一些可能存在的问题，或者需要重新讨论的问题，可以使用// FIXME: xxx 来注释。

// good case
function getNumber(number) 
  // FIXME: 这里不应该使用全局变量num
  num = 0;
  return number;

【推荐】 使用// TODO: 注释暂未实现或者待解决的问题

// good case
function getNumber(number) 
  // TODO: 这里的状态需要单独维护起来，不应该使用魔术数字。
  const status = 0;
  return number;

实战篇

怎么添加注释，以及注释的基本格式等内容，我们在规范篇已经清楚啦，实战篇，我们主要围绕实际项目开发中，有哪些地方需要加注释展开。

公共API添加注释

不管是vue还是react，项目中肯定会有一个专门utils文件夹去维护自定义的一些工具方法，这些方法我们要尽可能把注释加上，推荐使用j sdoc去添加注释。其次就是一定会有一个components目录去维护项目中的公共组件，那组件中定义的props，事件等也需要添加注释。

每个模块文件头部都添加注释

这里指的是，平时业务项目开发中，一定会拆分成很多不同的模块，同时，由于项目的类型不同，例如电商，医疗等不同类型，就会涉及到很多专业名词，因此，建议在每个模块的文件头部都使用多行注释，去说明当前模块是什么模块，以及包含哪些子模块等 。当然，这一点是我个人的开发习惯，大家根据实际情况决定即可。

/*
*  权限管理模块：
*  1. 权限列表
*  2. 添加权限
*  3. 权限详情
*/
​
// 代码部分
// ...

同时，在单个文件中，可能存在多个模块的变量，我们尽可能把相同模块的变量组织到一起，然后加一个统一的注释等。

逻辑复杂的代码块需要添加注释

在项目中，肯定会遇到那种逻辑比较复杂的场景，比如后端返回一个比较差的数据格式，自己需要做比较多的数据转换的操作，而且还要针对不同情况去做适配处理等，总之，就是很复杂，这时，我们也可以通过添加注释的方法，进一步说明一下。

还有一些代码逻辑比较重要，或者自己想强调一下，这个时候，也可以通过添加注释的形式去强调。

vscode注释插件推荐

这里，推荐两款：

• Better Comments：特点是可以改变注释的颜色，通过不同颜色来表示不同情况
• koroFileHeader：特点是可以在文件头部快捷添加注释和函数注释。

插件具体使用细节，可以参考官网即可。

总结

通过本节的介绍，相信大家已经对注释，以及如何去进行注释有了进一步的了解，总计下来

1. 核心还是代码质量，代码能表达清楚的，就不需要注释
2. 即然要加注释，就要把注释加的准确清晰完整。
3. 同时了解到了常见的需要加注释的场景。
4. 介绍了常用vscode注释插件。

接下来，就是大家在项目中，逐步去根据上面说到的这些点去应用到实际项目开发中，逐渐养成自己的习惯。