大家敲代码,会写注释么?似乎周围的朋友,就我一人写的程序木有注释的。

二麦麦 发布于 2014年08月18日
无人欣赏。

想表达的意思就题目说的一样喽,询问了旁边的几个朋友,我说我写代码从不来不写注释,而且公司里的传统就是基本不写注释,而他们只有诧异不可能惊讶的表情,也因此跟朋友争论了很久,后来么也就不了了之了。

个人觉得,写了代码完全没必要再去敲注释,好比你写了篇作文,尼玛的,你还要用中文解释一遍?难道为了凑够800个字?呵呵呵。如果你写的是文言文,好吧,say good bye to you,我们不是一个次元的人。

共40条回复
tinyfool 回复于 2014年08月18日

检测的标准其实很简单

如果你是一个solo工作者:

你找一个一个月前写的代码,去看,看得懂,OK,可以继续不写注释

如果你是一个team工作者:

把你的代码给同事看,看得懂,OK,可以继续不写注释

梦中醒不过来 回复于 2014年08月18日

Controller曾一般会写,声明下干什么用的,service和dao层一般不写

SteveLTN 回复于 2014年08月18日

嗯,我们公司 Style Guide 说原则上不允许注释。

如果你发现你的代码要写注释才能看懂,请重构代码,把逻辑抽象成方法,并且起一个一看就懂的名字。有东西实在想要解释,就写在 git commit message 里,别人发现代码难懂的时候 git blame 一下就知道谁写的这段代码,为什么写,甚至和这段代码一起改了哪些东西都一目了然。

写注释的缺点是容易有人改了代码而忘了改注释,造成误导。

我们是用 Ruby 的,开新方法很平常。有些对性能比较注重的领域,用 C 或 Java 的话,可能不适合这样做。

sleepinging 回复于 2014年08月18日

要看具体情况。我工地的工作经常牵涉到几个坐标系之间的计算,参数注释写清楚,大家都方便。或者你平时用的第三方开源库,如果没有注释都能明白么?

二麦麦 回复于 2014年08月18日

1楼 @tinyfool 一直坚持写无注释代码,现在也习惯了,把该注释的东西,都写进代码里了。

二麦麦 回复于 2014年08月18日

3楼 @SteveLTN 正解,把需要注释的东西,都写进代码,如果需要注释才能理解的代码,果断重构。

yangjie6020 回复于 2014年08月18日

到现在一行注释都没有写 我坚信 代码是个人看的 不需要注释

soupsue 回复于 2014年08月18日

我也是一个人复杂iOS app开发,从来没写过注释 😁

清醒疯子 回复于 2014年08月19日

注释是必须的。如果各种不行还好,可以直接炒掉。最麻烦的就是,又基本达标的,要炒掉吧,又不服。

不但要注释,只要是出X.X.X的版本都必须文档跟上。注释和文档都必须正规,不能按自己风格写。

newliuli 回复于 2014年08月19日

我们公司以前的代码也没有注释,前提是你写那东西得别人能看懂啊?所以现在还是要求有注释。我自己的注释重点不是代码内部,主要是模块设计的说明和模块接口参数说明。

cnsoft 回复于 2014年08月19日

重复提交了呢?

cnsoft 回复于 2014年08月19日

注释这东西存在必有合理之处. 用的不好 只能怪自己. 说什么不要注释 自己写就无所谓了. 要给别人看, 跳来跳去的流程没注释, 累死. 会意错了 全是bug. 是等着说别人用错了你的代码模块 是么。

netdigger 回复于 2014年08月19日

我会在代码稳定到一定程度才开始加注释,主要说明接口定义和模块定义。前期重构频率高,写注释和改注释的时间伤不起

CurveSoft 回复于 2014年08月19日

从来没写过注释,也没发生过别人看不懂我的代码的情况。只有干活干一半不得不中断的时候,会写个// TODO: ,接着干完也就删掉了

嗯,严格说也有别人看不懂的时候,但是哥们你都不知道@Autowired的变量从哪里来的,到哪里去找,我写再多注释有用么?

snoopy 回复于 2014年08月19日

我是习惯了写点注释,保证团队或自己看代码的时候能一眼就知道它的作用。

kuxinwei 回复于 2014年08月19日

自己写的时候还是会在关键的地方写上点注释的,毕竟不是只有自己看。之前看过android的EventBus,都到了v2了,没有demo,文档简略,一些很关键的地方连注释也没有。用这个库一有错就要自己把代码从头跟到尾,感觉无爱啊。看别人代码的时候还是希望在关键点或者关键方法写几句注释的。

easyfly 回复于 2014年08月19日

不写注释,如果你能够确保你的代码本身就能够表达清楚意思而且不会有bug的话,也行。 但是问题是很多人看了你的榜样从此染上了不写注释的毛病但是又bug一大堆,最后离职了,这叫接手的人怎么活? btw,我是写c++的,目前主要是大型软件的维护,修bug,以及根据需要增加新的功能。 去年花了三天时间把前人写的某个上万行代码的文件捋了一遍然后写了几百行的注释。 当我第二次(几个月之后)对这上万行debug正犯愁的时候,看到了注释,于是读完之后刷刷刷很快搞定了代码。

easyfly 回复于 2014年08月19日

1楼 @tinyfool 我的个人理解,在代码本身能够把意思表达清楚的情况下,没有注释是没有问题的。但是,代码是会有bug的,在有bug的情况下,还表达个什么意思呢?必须得有注释了。除非代码是绝对没有bug的,但是没有人能够保证这一点啊。

浅风渐微凉 回复于 2014年08月19日

我是一般接口上给个注释说明这些个接口都是什么作用的。

forzaJuve 回复于 2014年08月19日

楼上说 后面有人改了代码 不改注释 导致误导....

问题不还是因为不注意写注释啊...

你逻辑简单的代码不写注释也就算了...

逻辑非常复杂的业务你不写注释吗?

就算你拆方法拆得细 ,你就不担心跳来跳去把后面的人跳晕吗??

你隔了一两年还记得你当时的逻辑吗???

说白了就是懒, 还要找各式各样的借口.....

SteveLTN 回复于 2014年08月19日

20楼 @forzaJuve 复杂的逻辑必须重构,拆分成独立的模块,并且名字要一看就懂。名字起得好的话,你看了名字就知道干了什么,把它当做黑盒就行了,还要跳来跳去干嘛?

我们用 code review 流程保证代码可读性。任何人提交的 pull-request 都需要由其他两个人看懂才能通过,合并进 master。如果 reviewer 看不懂你的代码,你必须重构直到别人能看懂为止。就我目前的经验来说,从来没有遇见过无法重构到能看轻易看懂的代码(确实在性能很关键的领域可能没法重构,只能写注释)。

详细的说明文字写进 git commit message 里。如果读代码时不知道某段代码的作用,blame 一下就知道。

如此,代码自身解释了这段代码干了什么;git commit message 解释了为什么要写这段代码。

代码写的看不懂,不去重构代码,用注释这种简单粗暴的方式去隐藏问题,才是真的懒惰。

特诺兰的风 回复于 2014年08月19日

隐喻到位就不要加注释,不然就加注释,最简单的判断还是看读你代码的人是不是可以看懂

jokefaker 回复于 2014年08月19日

完全不写注释这也太夸张了点,就好比你给人家留出接口让别人调的,你不写注释怎么说明...

zt1991616 回复于 2014年08月25日

完全不写,隔几个月岂不是连自己都不认识?

syeerzy 回复于 2014年08月25日

只写以下几种注释: 1 可以文档化的注释(比如python里的 ''' 这种 ''' , 或者C#里的 ///这种 ) 这个注释可以由工具自动生成各种API文档, 并且可以被很多支持的IDE提取作为代码提示,作用是很大的. 2 如果代码里有一个位置反复改过2次以上, 那么无论自己是否需要,都要写上这个注释解释清楚. 3 修改不属于自己的代码,别人的代码里做的修改一定写上谁,什么时间,修改了什么 4 //TODO: //HACK: //UNDONE: .....这种注释 5 某些性能热点区域,为了追求执行效率而使用一些 magic 或者 至少看起来不太符合习惯做法的代码 (确实有时候优雅的代码和极端性能追求不可兼得) 这种情况只发生在确实测试出性能热点后的重构, 这个位置要注释,避免有别人为了代码看起来舒服,给你改回去了. 6 所有使用goto的位置. 都知道goto是不推荐乱用的, 那么如果有那么一些位置(很少发生,但确实有),确实使用goto是一种最佳或者更好的方案, 那么注释一下防止其他有洁癖的人把你几个非常简单的goto改成18层循环加递归加一堆临时bool状态变量... 7 某些跟一般情况不同的使用(比如正常这种东西要加锁互斥访问,而恰恰这个地方不需要, 或者反过来) 8 如果团队里大部分其他人在这个地方的技术不太好或者这个地方跟他们的认知可能有点区别(比如一个安卓团队里,临时做点ios的东西...), 那么有些区别位置需要注释,免得有人想当然...

最后, 第0点: 代码能自己说清楚的, 不要写注释. 如果代码在当前这个位置,有可能自己说清楚而现在没说清楚, 那么应该重构代码而不是注释. 一旦写了注释,就一定要保证注释和代码一致.

很多其他人回复了从不写注释,觉得代码 "一定" 可以自己解释自己. 我只能说你遇到的情况还太少了. 确实会存在一些无论如何你必须做出取舍的情况,并且牺牲可读性是更好的方案. 那么,你就需要注释.

虽然上面我列了很多条, 但是实际上这很多条大部分都是很少发生的,所以事实上我的代码里注释也是很少的.(除了第一条)

jingqq5210 回复于 2014年08月25日

21楼 @SteveLTN

你们的流程基本接近于理想状态,可有相关分享的博客之类的?

coderonloft 回复于 2014年08月25日

不写注释,就是作死,根本没理解软件工程的复杂性和问题的不可预见性。以不写注释作为炫耀的软件工程师,不适合团队工作。

jiaru0730 回复于 2014年08月25日

1楼 @tinyfool 简单有理,可以终结写还是不写,该怎么写的各种争论了。我遇到过最可怕的事情,是不仅代码不好理解,连注释也不好理解。

小七12138 回复于 2014年08月25日

注释的作用是让别人了解模块、接口的作用和用法的, 你提供的东西我用一下还得把你代码流程看一遍? 你代码就是写的再清晰, 用一遍你的功能就得浏览一遍你的代码,去看看每个参数都是干啥的, 累死个人啊

chrisilc 回复于 2014年08月25日

最近为公司的分布式平台底层实现了Paxos的算法,核心代码两百多行,注释写了将近100行,我觉得注释不是要说明你的代码在做什么,而是要说明为什么要这么做.

ljb_iss 回复于 2014年08月25日

原则上 代码就是最好的注释, 但 两个人面对面对话都有可能误解,何况代码是自己脑子里抽象模型的再次表达。

苹果的开源代码和linux的kernel 都还有注释呢。 完全没有注释的代码,只能说明这个代码太简单,或者没什么价值,别人不会看,甚至自己也不会长时间重复的看。

注释不是写不写的问题,是怎么写的问题。 自己的习惯:

  1. 接口必须写,因为接口是给别人看的。不写清楚,是浪费大家的时间。
  2. 复杂逻辑最好写,写以下这段代码要干什么,而不是做什么。
  3. 复杂算法,需要写,注明算法的逻辑。
  4. 特殊的优化,需要注明一下。
l20061642 回复于 2014年08月25日

// ┏ ┓   ┏ ┓ //┏┛ ┻━━━━━┛ ┻┓ //┃       ┃ //┃   ━   ┃ //┃ ┳┛  ┗┳ ┃ //┃       ┃ //┃   ┻   ┃ //┃       ┃ //┗━┓   ┏━━━┛ // ┃   ┃ 神兽保佑 // ┃   ┃ 代码无BUG! // ┃   ┗━━━━━━━━━┓ // ┃        ┣┓ // ┃     ┏┛ // ┗━┓ ┓ ┏━━━┳ ┓ ┏━┛ // ┃ ┫ ┫ ┃ ┫ ┫ // ┗━┻━┛ ┗━┻━┛ //

SteveLTN 回复于 2014年08月27日

26楼 @jingqq5210 我们自己没有写博客。我们的流程是向 thoughtbot (一家比较有名的 Ruby 咨询公司)学的,他们写了非常多类似的 Topic。

holly 回复于 2014年08月29日

告诉你们, 我的代码中注释通常比代码多

AngryYogurt 回复于 2014年08月30日

想写注释但是不知道该写点什么,有时候写了一大段代码然后翻上去一看哎呀好乱好难读啊,就在不好理解的地方加点注释

nkduqi 回复于 2015年11月06日

http://ourcoders.com/thread/show/6978/

lionlee 回复于 2015年11月06日

必须要写的,就和社交网络上的 Tag 一样,时间长了找个东西很麻烦,为自己也为团队。

人在江天 回复于 2015年11月07日

不写注释的情景是有, 但往往很少,大多是工具类或者工具函数的实现部分,而接口部分还是要写的。

如果是业务代码,不写注释基本上就是没有责任心。

pate 回复于 2015年11月08日

连接口都完全不写注释?单看名字也许能看出接口的大概作用,但各种边界条件、约束呢?

wise_joker 回复于 2015年11月13日

其实这个主题不是写不写注释傻不傻逼的问题,是你当前敲的代码有多大程度需要注释的问题,下面举两个栗子相信大家都能看得懂

  • 当你用python/ruby/swift,用着各种高级语言的特性,面向开发者的角度去编程,完全可以把代码写成文章一样,一眼就能看懂

  • 当你用C/汇编,面对性能问题不得不面对机器编程,使用各种适合机器的特性,不写注释?楼上几位高手帮我看下这段汇编是什么意思,这个寄存器里存的是啥?

事情都没有绝对,都要看情况看环境而定,楼主下次问问题的时候带上你用的什么语言写的什么项目几个人合作


顺便,@tinyfool 的沙发回答已经包含了我的解释,我只是给理解不了的人具体化下场景

本帖有40个回复,因为您没有注册或者登录本站,所以,只能看到本帖的10条回复。如果想看到全部回复,请注册或者登录本站。

登录 或者 注册
相关帖子
[顶 楼]
|
|
[底 楼]
|
|
[首 页]