大家注释怎么写的

[brucefeng]

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

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

问问大家都是怎么写的。

[ebony0319]

几个程序员去吃饭，有人点了一道菜，麻辣牛蛙，然后其中有一个人说自己不吃牛蛙，于是负责点菜的直接在麻辣牛蛙前面划了两道斜杠，

就像这样：//麻辣牛蛙

现场没有人觉得那里不对，
直到服务员上了 11 盘牛蛙。

[kaiku300]

// 当我写下这个的时候，只有上帝和我能够看懂

// 现在，只有上帝能看懂了

[warcraft1236]

不能理解不写注释。自己写的代码，过较长时间来看，很可能就需要花很长时间才能明白当初为啥要这么写。如果前后有多个人维护的，不写注释，别人怎么接手？难道接手前先通读一下代码，不了解的问？

[alexapollo]

代码即文档是非常高的水准，大部分公司的代码远远没有达到。

一般而言，代码水准分为三层：

* 写的烂的代码，基本没有注释
* 写的好的代码，有较多注释量（还需要有很多注释来说明 5W ）
* 写得优雅的代码，有一定的注释量（大部分不需要注释）

相信只有实力较强的公司（少之又少）才能达到第三层。达到第二层已经不错了。

[palmers]

这个尺度很难把握，怎么算是自说明代码呢？ 判断标准是什么？ 如果团队在后期利益上考虑代码注释问题，我觉得只要那位同事不要一行代码三行注释就不用管，毕竟你们团队没有明确的标准来规范代码注释, 个人是 除非负责的逻辑和业务才会简明额要的注释说明

[ffffwh]

@kaiku300
double penetration; // ouch

[ideascf]

一般来说，如果我认为一段代码，我不能在 10 秒以内或者更短的时间内读懂它，那么我就认为我需要加注释。

[ideascf]

私以为代码自注释都是扯淡。现在写的代码中，大部分都是业务相关的，业务相关的代码必然会有些业务相关的逻辑，而这些逻辑不是代码能清晰的说明 why 的；再且增加一些能简明达意的注释何乐而不为。

[lightening]

我们一般也是尽量代码自说明。

毕竟注释是一种偷懒的方法：代码逻辑不清晰了，应该重构代码使其一目了然，而不是简单写一段注释糊弄过去。况且，注释会骗人。

代码自解释是比注释更高的要求。并不是说难懂的代码就放着不写注释。不用注释的前提是代码必须非常清晰易懂。比如把逻辑抽象出去并用非常合理的函数名字描述。这种情况下对函数命名的要求非常高。

[lightening]

@milklee 不写注释当然是以把代码优化到一眼就能看懂为前提的。如果代码很难懂还不写注释就是作死。

注释带来的问题是：
1. 注释是可以骗人的
3. 事无巨细的写注释的话会造成重要的细节被藏起来难以发现


@ideascf
@ideascf
@ideascf

[lightening]

@ideascf Sorry ，由于网络卡顿 @ 了你好多次。

我们认为 10 秒内不能读懂的代码就应该改写成 10 秒能能读懂，而不是写一段 20 秒才能读完的注释。

另外，代码应该只是描述“做了什么”而不是“为什么这么做”。 Why 的问题我们放在每个 feature 的 git commit message 里，这样有人想看为什么这么写只要 git blame 一下就知道，而且可以一个 commit 当做一个整体看，避免断章取义。

这里有一个前提就是项目使用的语言语法是比较简洁的。如果用 Java ，这样做就显然不合适，因为创建一个方法的语法比注释还要麻烦了，看起来一点都不方便。

[JamesRuan]

我很少写注释，因为不需要。

只有向外暴露的接口才会写文档性质的注释，函数内部仅在少量可读性有问题的地方加注释，其他情况下都用代码自己说明问题。

[ideascf]

@lightening 的确，如果能优化到快速看明白(无论时抽取函数、清晰命名、提取脉络等)，那最好不过。 但在我实际工作经验中，我会经常遇到一些逻辑(很操蛋的逻辑)，并不能通过以上手段来达到使其清晰明了。

git blame 这个，我更倾向于在 git 的 log 中写'做了什么'。 再且，注释写在代码中，我能一目了然的获取到我想要的信息；我可不想再去 git blame 一个个的去翻 why 。

然后注释带来的问题这个：
1. 猪队友这种情况，真的只有认了
2. 注释的详细程度，应该有个合适的度。 一味的靠注释来阐述代码，那代码必然时糟糕的。

综上，我的观点是： 写必要的、简洁明了的注释，用来快速的理解 或 帮助回忆代码逻辑。 即，注释是辅助工具。

[Matrixbirds]

一般考虑写番号

[lightening]

@ideascf 当然，当你的逻辑无论怎么优化，但还是非常复杂的时候，注释是必要的。并不是说不能写注释，而是可以优化代码的情况下，尽量不要用注释来解决问题。

git log 可以有一个标题和一段文字，文字可以很长，详细解释为什么这么做。注释写在代码中的问题是，它不是一目了然的。如果要详细解释 why 的问题，这个注释会很长，反而导致了关键的地方不能一眼就从大段文字中分离出来。

[XDDD]

@stormpeach 这种情况显然应该用枚举

[techme]

改动的太频繁，已经没办法写文档了，干脆就把需求写到注释里

[linux40]

那个。。。 java 不是有一套标准来生成网页么，用那个不就好了。。。

[linux40]

新人对可能是为了以后很快能看懂吧。

[hlyang1992]

注释都是写英文的吗？