本文使用「署名 4.0 国际 (CC BY 4.0)」许可协议,欢迎转载、或重新修改使用,但需要注明来源。 [署名 4.0 国际 (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/deed.zh) 本文作者: 苏洋 创建时间: 2013年01月13日 统计字数: 2441字 阅读时间: 5分钟阅读 本文链接: https://soulteary.com/2013/01/13/comment.html ----- # 代码注释 [![Image](https://attachment.soulteary.com/2013/01/13/ascii-comment.png "Image")](https://attachment.soulteary.com/2013/01/13/ascii-comment.png) 在绝大多数现代语言中,我们越来越注意源代码的版面和样式,而在绝大多数现代的编辑器中,我们都有了可以依赖的插件,进行版式编排。 糟糕的排版会带来很多问题,比如下面这个: ```js ``` 当然,你会说,这种都是经验问题,踩过一个坑,就知道会执行到哪里了。 这个回答不需要反驳,但是你同样无法反驳:原来应该注意的细节被转移了,时间和精力被无辜浪费了,程序中的实际代码应该是可维护的,友好的,不是么。 如果要讨论每个细节的话,我们恐怕要坐一起面对面,讨论个三天三夜....那应该也不足以讨论完所有的细节,所以就注释,来简单的说一下我个人的看法吧。 代码注释是修建程序大厦中的锦上添花,而并非构建基础结构的基石,他只是提供对一个细节的额外指向和补充,并非完整的参考,如API文档,也并非规范内容。而且作为代码的贴身保镖,如果你的函数出现问题,那么首先应该被阅读到的就是注释。 重构时常常遇到这样的代码: ```php ``` 原作者在修筑的时候,肯定想到了什么,但是因为不是主要的功能,或者想后续完成,于是把第一个选择分支置空了,这时,或许应该在wiki或者这段分支中添加一点注释,告诉后人,这个版本先不需要这个功能,咱们下个版本添加。 否则在文档从几十行到几十kb/上百kb的时候,这个细节如果没有记录,或许早已被人忘记,而这些全部都是良性程序架构的潜在敌人。 我们常常在写文档的时候,就纠结于,我们该弄个多华丽的文档说明开头呢。 ```html ``` 一个ASCII艺术字,或者字符画一个鸟叔和欧巴刚那死大?看起来很绚丽,但是你需要这些注释帮你执行什么华丽或者伟大的壮举么? 显而易见的,他们只是注释,很多语言在执行编译的时候是抛弃注释的,比如C,当然也有很多语言的某些编译方式的选择不同,会在编译之后保留注释,比如VB。他们不是关键的组成成分,但是是必要的。 千万不要把时间耗费在大量不需要维护的注释上。 注释应该是高质量,而不是高数量的,就HTML结构来说,因为它看起来比较直观和简单。 因为在模版中,我们的HTML比想象中看起来要碎一点,原本是这样的结构: ```html
``` 可能会变成这样 ```html
``` 如果你知道你的结构可能变的很复杂,那么为什么不在建构之初这么写呢? ```html
``` 看起来注释是实际内容比重的6/11 ,但是他为以后的扩展提供了良好的指向。 但是相比较的这种注释就不友好了。 ```html
``` 如果你看完这段,觉得没有什么,那么我觉得你没有必要再接着看下去了。 这段结构充满非友好的书写,命名随意不统一,控件标签使用不规范,注释简直就是心理直白,或者说和代码之间的感情直播。 注释被滥用了,数量上和内容上,其实只需要把可能被程序填充,里面会出现大量结构的出入口写上范围注释,以及本段功能待定,出于SEO考虑,出于优雅降级考虑即可。写的人文艺,看的人舒心,而且还能解决问题。 一首曲子好听,不在于它是几个小时的歌剧,而关乎于它的旋律,优美的旋律,十几秒足以打动人心。 ```js ``` 这里的注释同样让人拙急,我们阅读至此,很大概率会跟下去看看这个函数是干嘛的,除非我们约定了强命名,以及我们很熟悉这个函数的具体实现。 而且在代码中重复注释是一件很不文艺&&很不普通的错误。 或许这么写会好点。 ```js ``` 我觉得注释应该实事求是和不扭曲事实,如果不确定,咱们就不确定就可以了。 ```js ``` 上面这段代码很容易把一个老实巴交的程序员带入万劫不复,如果这个是核心业务逻辑的话。 如果两个程序员关系很好,或者一时疏忽,很容易相信注释,或者是那个程序员自己查阅自己以前的注释,觉得是对的。 然后...我想就没有然后了... ```js ``` 这样的苦逼事情,我们经常遇到,为什么呢,一个是一时大意,没有实事求是的检查每一段代码,再一个就是注释的错误指向。 猴年马月的东西,没有在维护的时候被删除,于是...举个更夸张的例子,但是效果应该会很好。 ```js ``` 你看过之后是不是想说,原来网易和迅雷社区里的盖楼,咱们程序里也有啊-,- 有句话说的很好,过去的事情,就让他过去吧。 我们来看看一个头疼的事情 ```html
``` 这种大段不用的代码,常常在程序员考古的时候发现,某些项目临时上线,也会在页面中看到这个东西。 这个东西和之前上面说的问题是一致的,只会让后面的同事越来越迷惑,甚至保持和这个一致的习惯,就是把不用的东西防止代码中, 增加复杂度和文档大小。 如果你反驳我,这个以后可以用,好吧,我的看法是,你有git,svn呢,咱们可以记录版本的,干干净净的多好~ 如果你留下这些,难免在修改的时候分心,也不利于代码编写。 人各有志,啊不是,是魔术人人会变,人人技法不同,不需要苛求细节? 真的是这个样子么?我们来看一个小细节: ```js ``` 如果你要查找所有的todo,那么使用/\/\/TODO[ |:]/i搜索和使用//TODO:搜索的代价也是不同的。 当然,技术大牛或者正则着迷者可以无视这个事情,如果您真的觉得没有必要统一。 说了这么多,谈谈注释的排版吧 单行注释并非只可以使用//,如下: ```js ``` 常见的块级注释 ```js ``` 当然,有人建议注释也保持级别如这样: 我觉得这样只是浪费了程序员的精力,去关注收益比较低的事情。 ```html ``` 不过成对出现的东西,某些时候出现还是很有必要以及很直观的。 ```js ``` 吐槽一下:其实本来只是想分享一下简单的注释的样式和排版,木有想到又是一篇洋洋洒洒的流水账-,- 欢迎留言讨论,共同进步。