代码注释规范

引子

有句话叫“代码即注释”，好的代码本身就是注释，具有较好的可读性。比如使用有语义的方法名，和变量名。对于逻辑复杂的代码，是有必要写注释的。如果代码命名良好，结构合理，一般来说是不需要什么注释的。但是用一句话解释下意图和功能也是极好的，因为很多时候仅仅是想知道代码怎么用，读一句注释要比分析几十行代码快得多。
注释的价值在于：方便他人阅读和团队维护。

怎么写

好代码 > 差代码+好注释，好的注释是很有价值的，坏注释不仅浪费时间还可能有害，自解释的代码最好。好的注释不是重复代码或解释它，而是使代码更清楚。
对于方法的实现来说，把自己写代码时怎么思考的用精简的语言写下来，如果有例子，那就在注释里写上例子。
减少不必要的冗余注释。例如：i += 1 // i 加1。注释不在于多，而在于精。
请删除陈年的注释代码，不要舍不得丢掉。很多人想着万一以后要用的时候，可以一键恢复。你忘记了，咱们有git这个工具吗？
如果附上jira、bug、需求等的地址能够帮助理解代码，可以适当加上。
最后，请及时更新，每次修改，都要在注释后面写上修改者的姓名邮箱时间和修改原因以及修改内容的简要说明。

加注释的标准

复杂的业务逻辑

业务逻辑关联太多的东西又或者步骤非常多，更或者两者兼有，那么就很少有人会去耐心仔细的去一行一行的把整个代码全部读通理顺。
这时候，必须在业务逻辑实现的相关方法或组件中，把方法或组件实现了什么功能，为什么这么设计，以及对应的业务逻辑都要讲清楚。并且重构代码后，注释也必须跟着重构。
比如患教管理中的文章编辑功能、个案中的入院管理、计划管理，都是比较复杂的业务场景。

晦涩的算法

算法也要加上注释的，尤其那些深奥的算法。对于业务来讲，可能是一些计算规则，常见的有积分计算、价格计算、营养师分配、时间的差值计算、时间的格式化规范等等。

非常规写法

非常规的写法往往是有特殊情况，不得已为之的。比如，为了得到更好的性能；又比如，为了修复一个 bug，却不想对代码进行大改动。
非常规的写法就是反模式、反套路的，有时候甚至会违反程序员的直觉。像这些做法，必须在注释中写明这样实现的原因。

有坑却暂时没太好解决办法

有些时候，需求出的够难够复杂，时间上催的又很急，你根本没办法马上想到特别好的办法去实现。只能临时想个简单粗暴的方案，先凑活着。甚至还会在某些地方，把一些变量的值写死先去把本期的需求实现了。这时候，注释必须加上为什么要这么解决的原因，还必须加上 //TODO 这类的，表示后面需要进行进一步的修改。
常见的，比如在项目时间比较紧急的情况下，复制了一个文件目录进行修改，没有时间进行重构；使用一些hack的手法修复bug；想删除一些看上去无关紧要的代码，但会引发bug等等。

组件注释规范

注释分类

总结注释

简化代码为一句或两句话，这种注释比重复代码更有价值，能帮助人快速理解代码。

useEffect(async () => {
  const curingOrgId = await getCurringOrgId()
  setCacheCurringOrgId(curingOrgId)
}, [])

// 将在治治疗组id缓存到本地，便于在接口请求的时候，直接从缓存中读取curringOrgId，实现个性化请求。
cosnt setCacheCurringOrgId = (orgId) => {localStorage.setItem('curringOrgId', orgId)}

意图描述注释

解释代码的目的。意图注释在问题一级上，而不是在答案一级，是一句利用答案的总结描述。比如一些hack，阐述为什么要使用hack，解决的是什么具体问题，常见的有：浏览器兼容性，系统的兼容性等。

.ie-fix {
  _height: 0 // hack ie6 的样式问题
}

标记注释

TODO、TOFIX 标记等，经验表明，往往写了 TODO 后来就一直成了 TODO，所以最好提交代码前把要做的 TODO 做完，TODO 仅仅作为一次代码合并之前的提示。TODO 注释记得加上姓名，日期，联系方式和提示，方便查找。

// TODO 需要支持随访计划
const showPlanModal = () => {}


const scrollToTop = () => {
  // TOFIX 需要兼容iOS的滚动问题
}

注意事项

不推荐使用自动添加文件注释的插件，考虑到团队维护的成本，别人改了文件后，你把代码更新掉，哪怕只是一个保存，也可能会自动更新注释上的时间，其实是没有必要的，而且容易起冲突。
如果对部分代码进行了重构，那么相应的代码注释也需要做同步的修改，不然会容易出现代码和注释不匹配的情况，让人一头雾水。
我们经常会 copy 一部分代码拿来重写或者重用部分代码，那么修改的部分，务必也需要同步修改注释，否则也容易出现代码、注释不匹配的情况。