你习惯写注释吗？

作为代码从业者，大部分估计都参与过这样的话题讨论：到底要不要写注释？两派的论据是这样的：

• 正方：写注释是帮助看你代码的更快的理解，避免一些理解错误，尤其是业务较重的项目，上下文复杂

• 反方：代码经过几手之后，可能有人更新了你的逻辑忘了或者不想更新注释，这样的注释可能起反作用

其实这两者在现实生活中都遇到过，写了注释确实可以提升阅读效率，也有改了几百手的代码面目全非，注释形同虚设，也有压根就不看注释的人。

以 Java 为例，Java 的 checkstyle 为例，它的建议是所有的 public 方法都必须写注释。其实是一个好建议，对外提供服务的方法你需要详细的说明用途和调用方式等等，并且开启 checkstyle 之后会在编译期强制检查，逼迫开发者去写。但这还是不能解决不更新注释的问题，除非结合 git 再来一次变更后强制更新的检查，这就有点变态了。但开启检查之后，确实能解决一大部分问题。

拒绝写注释的人也不能完全否定，有些人是懒，有些人是拒绝。懒的人没什么好说的，但有意思的是每一次科技进步都是在为懒人服务，洗衣机、手机之类的，让人坐家里就可以把活干了。没错，这个世界就是勤快的人在为懒人服务，赚懒人的钱，死肥宅真的挺有钱的。那部分拒绝的人给出的替代方案，通俗易懂的方法和变量命名可以当注释看。说的也没错，但执行起来没那么容易，对开发者的英文水平和命名水平要求很高，即使用上 checkstyle，只能做格式的检查，没法检查语义。但好处是，后面有人即使改代码一般也不会轻易改方法名和字段名，因为关联的地方可能有很多。但如果被改了处理逻辑，可能也是一个坑。

说到底，后来的人乱改代码跟注释不注释没什么关系，企图从这方面来解决这个问题不现实。但注释的方法论是什么呢？我的建议是挑着写：

• 直接对外服务的 API 一定要写，而且要写的很详细

• 内部逻辑的关键节点，比如依赖的中间件，异步处理，数据库操作

• 比较复杂的设计，代码上看起来比较绕，但又没什么好的优化策略