《代码整洁之道》总结——注释

Posted 2020-09-29

注释

1. 好代码不需要注释，或者只需要少量注释，代码就能表达意图——回到上一篇内容，这要求我们写小且精的函数。（不要用这个借口不写注释）
2. 好的注释应该是这样的。如：对抽象意图或者深远意义的解释；阐述长且难读的函数（这种难读不是因为代码写得烂，而是名字都太长或者容易混淆概念）；警示一些关键重要的部分（这些部分一般是关键变量或者容易误解并出错的地方）；TODO注释提醒并告知未来要做的事；学着公共API的JAVADOC写就是好注释（虽然也有少数烂注释）；
3. 烂的注释往往是这样的。如：多余的注释（简单函数强行加上注释，读源码会比注释更快）；误导的注释（注释本来就是错的，可能源自你更新了代码没更新注释）；注释掉的代码；废话太多的注释。