Image

在绝大多数现代语言中,我们越来越注意源代码的版面和样式,而在绝大多数现代的编辑器中,我们都有了可以依赖的插件,进行版式编排。

糟糕的排版会带来很多问题,比如下面这个:

当然,你会说,这种都是经验问题,踩过一个坑,就知道会执行到哪里了。

这个回答不需要反驳,但是你同样无法反驳:原来应该注意的细节被转移了,时间和精力被无辜浪费了,程序中的实际代码应该是可维护的,友好的,不是么。

如果要讨论每个细节的话,我们恐怕要坐一起面对面,讨论个三天三夜….那应该也不足以讨论完所有的细节,所以就注释,来简单的说一下我个人的看法吧。

代码注释是修建程序大厦中的锦上添花,而并非构建基础结构的基石,他只是提供对一个细节的额外指向和补充,并非完整的参考,如API文档,也并非规范内容。而且作为代码的贴身保镖,如果你的函数出现问题,那么首先应该被阅读到的就是注释。

重构时常常遇到这样的代码:

原作者在修筑的时候,肯定想到了什么,但是因为不是主要的功能,或者想后续完成,于是把第一个选择分支置空了,这时,或许应该在wiki或者这段分支中添加一点注释,告诉后人,这个版本先不需要这个功能,咱们下个版本添加。

否则在文档从几十行到几十kb/上百kb的时候,这个细节如果没有记录,或许早已被人忘记,而这些全部都是良性程序架构的潜在敌人。

我们常常在写文档的时候,就纠结于,我们该弄个多华丽的文档说明开头呢。

一个ASCII艺术字,或者字符画一个鸟叔和欧巴刚那死大?看起来很绚丽,但是你需要这些注释帮你执行什么华丽或者伟大的壮举么?

显而易见的,他们只是注释,很多语言在执行编译的时候是抛弃注释的,比如C,当然也有很多语言的某些编译方式的选择不同,会在编译之后保留注释,比如VB。他们不是关键的组成成分,但是是必要的。

千万不要把时间耗费在大量不需要维护的注释上。

注释应该是高质量,而不是高数量的,就HTML结构来说,因为它看起来比较直观和简单。 因为在模版中,我们的HTML比想象中看起来要碎一点,原本是这样的结构:

可能会变成这样

如果你知道你的结构可能变的很复杂,那么为什么不在建构之初这么写呢?

看起来注释是实际内容比重的6/11 ,但是他为以后的扩展提供了良好的指向。

但是相比较的这种注释就不友好了。

如果你看完这段,觉得没有什么,那么我觉得你没有必要再接着看下去了。

这段结构充满非友好的书写,命名随意不统一,控件标签使用不规范,注释简直就是心理直白,或者说和代码之间的感情直播。

注释被滥用了,数量上和内容上,其实只需要把可能被程序填充,里面会出现大量结构的出入口写上范围注释,以及本段功能待定,出于SEO考虑,出于优雅降级考虑即可。写的人文艺,看的人舒心,而且还能解决问题。

一首曲子好听,不在于它是几个小时的歌剧,而关乎于它的旋律,优美的旋律,十几秒足以打动人心。

这里的注释同样让人拙急,我们阅读至此,很大概率会跟下去看看这个函数是干嘛的,除非我们约定了强命名,以及我们很熟悉这个函数的具体实现。

而且在代码中重复注释是一件很不文艺&&很不普通的错误。

或许这么写会好点。

我觉得注释应该实事求是和不扭曲事实,如果不确定,咱们就不确定就可以了。

上面这段代码很容易把一个老实巴交的程序员带入万劫不复,如果这个是核心业务逻辑的话。

如果两个程序员关系很好,或者一时疏忽,很容易相信注释,或者是那个程序员自己查阅自己以前的注释,觉得是对的。

然后…我想就没有然后了…

这样的苦逼事情,我们经常遇到,为什么呢,一个是一时大意,没有实事求是的检查每一段代码,再一个就是注释的错误指向。

猴年马月的东西,没有在维护的时候被删除,于是…举个更夸张的例子,但是效果应该会很好。

你看过之后是不是想说,原来网易和迅雷社区里的盖楼,咱们程序里也有啊-,- 有句话说的很好,过去的事情,就让他过去吧。

我们来看看一个头疼的事情

这种大段不用的代码,常常在程序员考古的时候发现,某些项目临时上线,也会在页面中看到这个东西。

这个东西和之前上面说的问题是一致的,只会让后面的同事越来越迷惑,甚至保持和这个一致的习惯,就是把不用的东西防止代码中,

增加复杂度和文档大小。

如果你反驳我,这个以后可以用,好吧,我的看法是,你有git,svn呢,咱们可以记录版本的,干干净净的多好~

如果你留下这些,难免在修改的时候分心,也不利于代码编写。

人各有志,啊不是,是魔术人人会变,人人技法不同,不需要苛求细节?

真的是这个样子么?我们来看一个小细节:

如果你要查找所有的todo,那么使用/\/\/TODO[ |:]/i搜索和使用//TODO:搜索的代价也是不同的。 当然,技术大牛或者正则着迷者可以无视这个事情,如果您真的觉得没有必要统一。

说了这么多,谈谈注释的排版吧

单行注释并非只可以使用//,如下:

常见的块级注释

当然,有人建议注释也保持级别如这样: 我觉得这样只是浪费了程序员的精力,去关注收益比较低的事情。

不过成对出现的东西,某些时候出现还是很有必要以及很直观的。

吐槽一下:其实本来只是想分享一下简单的注释的样式和排版,木有想到又是一篇洋洋洒洒的流水账-,-

欢迎留言讨论,共同进步。