大家注释怎么写的

[brucefeng]

最近团队开始有新人进入，在写代码注释上，有一些不同点。之前团队提倡的是尽量少写注释，让代码有自说明的作用，如果实在无法通过代码表达，再在接口 /方法级别写注释，其他地方不再多加注释了。

新人的注释习惯比较多，有的系统对关键代码行写步骤注释，有些接口和实现都有注释，有时候注释太多，感觉影响代码。

问问大家都是怎么写的。

[williamx]

代码自说明

注释也写，主要的作用是因为它的颜色不同，能突出重点。

[500miles]

我也认为 应该尽量少写注释, 保持代码简洁易懂, 让代码自己说话....

可惜, leader 坚持规定了一套面条式注释规范, 真是烦得不行 感觉好乱,

[expkzb]

@500miles 搞个 ide 插件来过滤注释如何

[SoloCompany]

只要注释不是代码的简单重复，并且有良好的格式做保障，多一点注释没有什么坏处
我只反对一种注释，就是把无用的代码框起来那种

[qiaobeier]

大项目需要 JSDoc 这种注释输出成文档的工具，小项目么随便搞搞算了。代码里的注释尽量精简，除非你写这个代码是为了学习。

[repus911]

函数一般不写注释，代码自说明
有时候写复杂逻辑的时候会先用注释写步骤，写完也不会删掉...
别人的代码一般不会动（不要乱动别人的代码），但是自己造代码写完会站在第三人的立场上根据复杂度酌情加注释。（跟上句不同的是，上一句是一开始就知道复杂，这里是越写越复杂，可能是因为逻辑也可能是因为业务）
“尽量少写注释”。。。无法理解，程序员都闷到这种地步了么，注释这种交流方式都放弃了。。。之前看到注释里一句“ TMD 疼讯 XXX ”笑了半天，感觉这个人好有趣

[qwerasdf]

根据阅读注释者的理解能力写不同的注释。

[zhouthanos]

企业里很多代码是按照和产品商定的业务逻辑来写的，这部分如果不写注释，后面接手的人会非常痛苦

[stormpeach]

在需要注释的地方注释，比如一个值可能是 1 、 2 、 3 ，分别代表什么意思得注释吧。一般是在接口注释一下

或者在文档里面写明也可以

[SpicyCat]

javadoc 的注释还是建议写。
接口肯定要写注释，而且要写得详细，跟说明书似的，让人一看就知道怎么用你的接口。
私有方法看情况，一般一句话就行。
class 的注释也可以写。
成员变量等，看情况，把一些重点的写写。

至于方法内部的注释，要少而精。

[kylefeng]

以前公司的规范是：

1. public 的方法必须写注释，而且要用 javadoc 注释（ /** blah blah blah */ ）说明参数和返回值。
2. 类、接口的声明必须通过 javadoc 注释说明该类、接口是用来干什么的。
3. 类的字段必须通过 javadoc 注释说清楚字段的作用。
4. java 文件头部必须带公司版权信息的注释。
5. 通过良好的命名和简洁易读的代码避免过度注释，复杂的业务逻辑可以通过注释来总结和解释。

这几点是最基础的，尤其是接口，经常会打包成 jar 给其他团队使用，注释写得好可以节约很多沟通成本。并且注释规范这个事情需要团队达成共识，甚至需要上面技术 boss 强制要求下来严格执行，不符合规范不让 merge 代码。

推荐一本书 《易读代码的艺术》 https://book.douban.com/subject/10773334/
第五章专门讲了作者对代码的注释一些观点，挺好的。

[msg7086]

听过一句话叫代码里的 Bug 都是基于错误的假设。
所以写函数注释的时候，特别要写清楚你实现这个函数时所用到的假设。
假设输入不能为空，假设输入一定是个数组，假设某个数是[0..3]之间，等等。
这样就算出了 Bug ，你的同事也不需要浪费几天时间去读你代码的实现，只要读一下注释就能发现问题了。

[visonme]

这个还真是没有统一的标准。
我们一般都是：
1.能代码自说明的尽量少注释
2.全局变量必注释
3.函数内部不做注释（或少注释） ，函数注释写结果和逻辑步骤
3.类 /对象写应用场景.作用 (成员变量注释， public 注释， private/protect 少注释)

[realpg]

几眼就看得明白的东西 原则上只写一个一句话功能说明 特别简单的功能说明也可以省略
复杂一些的 多写点注释没所谓
不爱看的 自己本地 IDE 做一个设置屏蔽掉显示就是了

[milklee]

为什么要少写注释？

以前我也几乎不写注释，后来要修改代码时本来只是要修改很少一部分，但早已忘了当时的自己的思路是什么，所以又只能重读所有代码，就为了搞清楚自己当时的思路；有的代码写的很奇怪，我隐约记得我当时这么写是有原因的，可具体原因我却忘了。

维护自己写的代码尚且如此，更别提维护别人的代码、或是让别人维护自己的代码了。

所以现在我习惯性的多写注释，每一个函数都有说明，代码奇怪的地方写上为什么这么写，并且尽可能详细。当然，我不会写“这里的数字加一”这样一眼就看的出来的注释。

注释多了的好处就是，无论过了多久，你不用看代码都知道这些代码是干什么用的。如果我要改一个地方，应该在哪修改、有坑的地方都能一目了然。把你的思路都写在注释里，这为日后别人修改或你自己修改都节省了不少时间。

[yjd]

同意楼上。久了就忘光，然后要修改需要花很多时间重读。有注释就快多了。

[wizardoz]

原来一个同事想推广他从华为带来的那套方法。在函数头注明调用了那些函数，以及被哪些函数调用。真真觉得神经病！

[sc3263]

@wizardoz 原来公司的代码里也看到过这种注释方法，坑的不要不要的。严格执行吧，其他地方增加调用你的函数了，你的文件就得改，即使说改的是注释。不严格执行吧，那加这玩意儿干啥？

[omygod]

多些注释 少一些坑 ， 这个没商量

[zpole]

v2 真是一个神奇的地方。几个月前还看到有人发帖抱怨说别人不写注释，自己接手怎么怎么辛苦的。现在就大家都提倡“代码自说明”了？（斜眼笑）你们高兴就好。