大家注释怎么写的

V2EX = way to explore

V2EX 是一个关于分享和探索的地方

现在注册

已注册用户请登录

这是一个创建于 3117 天前的主题，其中的信息可能已经有所发展或是发生改变。

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

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

问问大家都是怎么写的。

第 1 条附言 · 2016-06-12 17:04:36 +08:00

看到留言，可能大家对于不写注释，而使用代码自说明有误解。

不写注释而使用代码自说明，不代表代码写的没有人能看懂，而是对代码中的函数命名，变量命名等有更明确的要求，让其他人看到这些名字就知道所要表达什么内容，是让代码自己起到注释的作用。但是因为有时候对业务流程等这些逻辑较为复杂的地方用代码可能已经难以表达全貌，或者难以做到一目了然，所以只能在接口级别做注释说明，比如写上这个接口的方法经历哪些流程等。

注释

代码

行写

新人

64 条回复 • 2016-08-19 04:55:10 +08:00

williamx

2016-06-12 13:00:55 +08:00

代码自说明

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

500miles

2016-06-12 13:03:32 +08:00

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

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

expkzb

2016-06-12 13:07:41 +08:00

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

SoloCompany

2016-06-12 13:51:02 +08:00

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

qiaobeier

2016-06-12 13:56:29 +08:00

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

repus911

2016-06-12 14:02:07 +08:00

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

qwerasdf

2016-06-12 14:02:58 +08:00

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

zhouthanos

2016-06-12 14:07:21 +08:00

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

stormpeach

2016-06-12 14:12:22 +08:00

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

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

SpicyCat

2016-06-12 14:51:16 +08:00

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

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

kylefeng

2016-06-12 15:06:08 +08:00

以前公司的规范是：

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

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

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

msg7086

2016-06-12 15:34:37 +08:00

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

visonme

2016-06-12 15:43:32 +08:00

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

realpg

2016-06-12 15:44:26 +08:00

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

milklee

2016-06-12 15:46:25 +08:00 via iPhone

为什么要少写注释？

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

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

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

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

yjd

2016-06-12 15:54:06 +08:00

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

wizardoz

2016-06-12 15:59:56 +08:00

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

sc3263

2016-06-12 16:14:42 +08:00

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

omygod

2016-06-12 16:35:02 +08:00

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

zpole

2016-06-12 16:53:09 +08:00 via iPhone

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

ebony0319

2016-06-12 16:58:56 +08:00 via Android

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

就像这样：//麻辣牛蛙

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

kaiku300

2016-06-12 17:07:17 +08:00

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

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

warcraft1236

2016-06-12 17:08:49 +08:00

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

alexapollo

2016-06-12 17:09:30 +08:00

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

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

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

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

palmers

2016-06-12 17:11:50 +08:00

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

ffffwh

2016-06-12 17:19:04 +08:00

@kaiku300
double penetration; // ouch

ideascf

2016-06-12 19:27:08 +08:00

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

ideascf

2016-06-12 19:30:51 +08:00

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

lightening

2016-06-12 19:38:18 +08:00

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

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

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

lightening

2016-06-12 19:41:43 +08:00

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

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

@ideascf
@ideascf
@ideascf

lightening

2016-06-12 19:46:22 +08:00

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

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

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

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

JamesRuan

2016-06-12 19:50:54 +08:00

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

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

ideascf

2016-06-12 20:48:45 +08:00

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

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

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

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

Matrixbirds

2016-06-12 21:26:26 +08:00

一般考虑写番号

lightening

2016-06-12 21:44:27 +08:00

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

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

XDDD

2016-06-12 22:15:53 +08:00 via iPhone

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

techme

2016-06-13 00:14:35 +08:00

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

linux40

2016-06-13 07:12:06 +08:00 via Android

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

linux40

2016-06-13 07:14:01 +08:00 via Android

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

hlyang1992

2016-06-13 08:09:21 +08:00 via Android

注释都是写英文的吗？

rashawn

2016-06-13 08:16:03 +08:00

代码里注释写的少 git commit 的时候写详细一点都干了啥怎么干的也可以啊

penjianfeng

2016-06-13 08:16:29 +08:00

没有注释的代码都不是好代码,说什么少些不写代码的你去当下接盘侠就知道什么叫做 f**k 了狗的感觉了

nellace

2016-06-13 08:51:19 +08:00

讨厌看没有注释的代码

然而自己也不怎么写。。。。。

kisnows

2016-06-13 09:16:43 +08:00

当接手别人的代码的时候，就知道不写注释有多么坑了。你需要花很多时间来理解前人的一些‘小技巧’，代码自注释太理想了，即使他命名非常规范，但你要理解一段代码内容还是得把多有的代码读一遍，如果有注释了，那就能节约很多时间了。

ango

2016-06-13 09:31:07 +08:00

注释两个标准：
1 、方法 /类，头声明注释；
1.1 如果有必要，注释需要添加使用实例；
1.2 如果为接口类，需要把 wiki 相应的文档地址注释上去。

2 、代码块注释，注释必须与代码分行写，不可写于代码末尾；
2.1 简单写步骤说明。
2.2 算法逻辑简要说明。（或者计算公式）

良好的编码习惯是很重要的，不要为简而简。（多年前实习的时候，某位前辈教的）

sfree2005

2016-06-13 09:39:19 +08:00

让别人可以快速看懂你的代码，除了注释和代码本身的简洁明了之外，还有测试。单元测试可以说是将说明和例子结合到一块了。就像查字典，解释下面跟着就是例句了。

ajan

2016-06-13 09:45:47 +08:00

基本不写注释。。。

unknownservice

2016-06-13 10:38:53 +08:00

// 宫保鸡丁
鱼香肉丝

zealotpz

2016-06-13 11:13:52 +08:00

/**
* 没注释给你看
* 好不容易写出来的
* 你花点力气看也是应该的
*/

YzSama

2016-06-13 11:21:36 +08:00

注释必须写。
虽然麻烦点，但是为了自己也为了别人。

aksoft

2016-06-13 11:49:02 +08:00

头回听说注释会影响代码。。

xylophone21

2016-06-13 14:55:18 +08:00

两种情况下写注释：
1. API ，别人看不到你的实现或者懒的看，不方便看等情况
2. 坏味道代码，各种临时实现，其它模块的 Bug ，深坑，奇怪的需求等等，注释到这以后再改。

其它注释一般来说不主动，不表态，不拒绝

octopole

2016-06-13 15:04:20 +08:00

注释有一个点很重要，你我都能看得懂，不觉的多余，刚刚好需要。

wmhx

2016-06-13 15:15:02 +08:00

函数和重要的变量是要有注释的, 其他无所谓了.

8023

2016-06-13 23:46:29 +08:00 via Android

个人习惯把注释写的非常详细, 也是因为我刚开始学写程序时英语水平不好变量名函数名类名都是各种拼音简写甚至"一个变量""又一个变量"的拼音, 如果不写注释的话以后看起来很麻烦. 现在因为水平的逐步提高, 命名规则也逐渐走上正轨, 注释的习惯却保留了下来. 每一个函数的编写日期, 实现功能, 参数说明, 甚至还包括如何调用(何时会调用, 如何调用的例子)... 变量在哪里用到之类的. 几乎是每行都加注释. 已经成了习惯... 然而我只是自己写着玩儿或者说是学习, 还没工作.

haozina

2016-06-15 12:59:48 +08:00

拿到一个 9 年前的项目做升级，注释太少看得太痛苦，业务还很复杂。

stormpeach

2016-06-15 18:19:49 +08:00

@XDDD 嗯，但是有时候一些状态码会需要很长的解释

ericpeng

2016-06-20 11:39:47 +08:00

代码自说明适合一个人独立的 web 项目（纯 web 逻辑不复杂）。

一个大项目包含数十个小项目，每个小项目数十万行代码，不写注释，依靠自说明就完了。

顶级大牛的代码都是注释特别多（如同使用文档，减少沟通成本），代码特别精简（写注释的过程就是梳理思路的过程，会重构代码）。参考顶级项目的源码。

ericpeng

2016-06-20 11:47:11 +08:00

我接手的某公有云的代码，不写注释看得很累，各种小的设计 trick ，每次都要找到原来的作者才能理解，而且还不合理，浪费大量时间。每个小项目都是多个人经手，每个接盘侠都要骂前面的作者；为了不让下一个接盘侠骂自己，我还是好好写注释和重构代码。

franklinyu

2016-06-20 16:08:10 +08:00

@8023 編寫日期可以交給版本控制系統；參數說明、調用方法和例子等信息，應該寫入「文檔」而不是註釋。

franklinyu

2016-06-20 16:11:11 +08:00

我認爲基本不應該有註釋，但是應該有文檔。 Javadoc 就挺夠用的，集成開發環境也廣泛支持 Javadoc 。

franklinyu

2016-06-20 17:01:05 +08:00

我的想法跟 @lightening 差不多：公有函數，文檔一定要寫夠；私有函數，按照名字的直觀性判斷是否寫文檔，沒辦法用函數名和參數名來自行解釋的，就寫上文檔；文檔裏面不寫怎麼實現的（ how ），只寫實現了什麼（ what ），調用了以後會發生什麼；至於怎麼實現的，用了哪些技巧，碰了哪些釘子，都寫到 commit message 裏面，當作筆記來用。

8023

2016-06-23 13:35:28 +08:00

@franklinyu 学习到了, 多谢.

ihuotui

2016-08-19 04:55:10 +08:00 via Android

业务接口可以注释，其他函数如果需要注释证明复杂度太高了