几乎所有的软件工程师，都追求写出漂亮的代码，但是在学如何写好代码的同时，却很少有人关注写好代码注释的重要性，有的工程师从来都不写注释，认为 talk is cheap，也有的工程师写出的注释会让原本已经难以维护的代码，变的更加难以维护。好的注释往往能起到画龙点睛的作用，提高我们维护代码的效率。对于如何写好注释，我总结了以下几点：
1. 不写无意义的注释
// 从服务端请求数据
getDataFromServer();
无意义的注释就像废话一样多余，明明代码已经很清楚的表达“从服务端请求数据”了，却又添加了一行跟代码表达的意义一模一样的注释。不仅没给我们带来任何更多的信息，而且还随着需求的不断变化，可能会演变出下面这个问题。
2. 不要修改了代码逻辑，却不修改注释
// 从服务端请求数据
getDataFromCache();
当需求改变时，我们修改了代码逻辑，却不随之修改代码注释。就像上面代码里写的，明显注释与代码表达的意义不一致。这样的注释会让维护者迷惑，因为可能会真的认为 getDataFromCache() 的方法里封装了从服务器请求数据的能力。但是检查了方法内的逻辑可能才发现事实并不是这样。这样的注释，无形之中增加了我们的维护成本。
3. 不要写只有 TODO 或者 FIX 的注释
// TODO
getDataFromCache();
TODO 与 FIX 是很好用的代码注释标签，不仅能帮助我们快速的统计到 TODO 与 FIX，还可以指导我们后续需要继续跟进的事项，但是我维护过的不少代码里，有时只有一个孤零零的 TODO 作为注释，这会让我非常难受，因为根本无法清楚这里的代码还有哪些未完成的功能，这个时候通常只能祈祷写这个 TODO 的同学还未离职，但你找到他询问的时候，很可能连他自己都已经忘记为什么这里有一个 TODO 的注释了。所以你甚至可以不写注释，但千万别只写一个 TODO。
4. 在合适的项目里写英文注释
曾经有段时间，我认为英文代码似乎只有配上英文注释才显得自然优雅。而且优秀的开源项目与系统源码也都是这样做的，因此我也开始只写英文注释。但是直到有一天，我看到团队里的新手工程师在理解代码逻辑已经很困难的情况下，还要理解语法可能都不对的英文注释时，我重新思考了这个问题，并有了新的理解：如果我们是在做个人项目，开源项目或者团队中有国外开发者，那我们确实应该统一使用英文注释。但是如果我们是在一家国内公司做商业项目，当我们无法确定团队里的每一个人都能准确的理解英文注释时。为了项目的开发效率与维护成本考虑，我建议使用中文注释。
写好注释一点也不难，注意好前面几点，再克服一点点惰性，连不会写代码的人都能写好注释了。好好写注释，你的一行注释可能会给另一位工程师节省一下午的时间。
网友评论