本文使用「署名 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
```
吐槽一下:其实本来只是想分享一下简单的注释的样式和排版,木有想到又是一篇洋洋洒洒的流水账-,-
欢迎留言讨论,共同进步。