26.用代码沟通

“如果代码太杂乱以至于无法阅读,就应该使用注释来说明.精确解释代码做了什么,每行代码应该加注释,不用关为什么要这样编码,只要告诉我们到底是怎样做的就好了.”

通常程序员都很讨厌文档,这是因为大部分文档都与代码没有什么关系,并且越来越难保证其符合目的的最新情况.这不是违反了DRY原则(不要重复你自己Don’t Repeat Yourself ,见[HTOO]),还会产生是人误解的文档,这还不如没有文档.

建立代码文档无外乎两种方式.利用代码本身,利用注释来沟通代码之外的问题..

广告：个人专属 VPN，独立 IP，无限流量，多机房切换，还可以屏蔽广告和恶意软件，每月最低仅 5 美元

如果必须通读一个方法的代码才能了解它在做了什么,那么开发人员要投入大量的时间和精力才能完成它. 不需要注释来包裹你的代码的代码反过来讲,只需短短几行注 释说明方法 Don't comment to cover up行为,就可以让生活变得轻松许多.开发人员可以很快了解它的意图.它的期待结果,以及应该注意之处------这可省了你不少劲儿.

应该文档化你所有的代码吗?在某种程度上说,是的.但这并不意味着要注释绝大部分代码,特别是在方法体内部.源代码可以被读懂,不是因为其中的注释,而应该是由于本身优雅而清晰------变量名运用正确.空格使用得当,逻辑分离清晰,以及表达式非常简洁.

如何命名很重要,程序元素的命名是代码读者必须的部分.通过使用细心挑选的名称,可以向阅读者传递大量的意图和信息.反过来讲,使用人造的命名范式会让代码难以阅读和理解.这些范式中包括的底层数据类型信息.会硬编码在变量名和方法名中.形成脆弱,僵化代码,并会在将来造成麻烦.

使用细心 挑选的名称和清晰的执行路径.代码几乎不需要注释.实际上,当Andy和 Dave Thomas联手写作第一本关于Ruby编程语言的书籍时(即参考文献),他们只要阅读将会在Ruby解释器中执行几行代码.几乎就可以把整个Ruby语言的相关细节记录下来.代码能够自解释.而不是依懒注释.是一件很好的事情,Ruby在创建者松本行弘是日本人.而Andy和Dave除了sukiyaki和sake之外一句日语都不会.

如何界定一个好的命名呢?良好的命名可以相读者提供大量的正确的信息.不好的命名不会传达任何的信息.,糟糕的命名则会传递错误的信息..

例如:,一个命名为readAccount()的方法实际所做的却是向硬盘写入地址信息.这样的命名则是被认为是最糟糕的(是的这确实发生过,参见[HTOO]).

Foo是一个具有历史意义,很棒的临时变量名称.但是它没有传递作者的任何意图.要尽量的避免这种神秘的变量名.不是说命名短小就等于神秘.在许多的编程语言中.通常使用i来表示循环索引变量,s常被用来表示一个字符串.这在许多的语言中都是惯用的用法.虽然很短小.但是并不神秘.在这些坏境中使用s作为循环索引变量.可真不是什么好的主意,名为indexvar的变量也同样不好.不必费尽心机去用繁复冗长的名字替换大家已习惯的名称.

.对于显而易见的代码,增加注释,也会有同样的问题,比如在一个类的构造器方法后面加这是//Constructor就多此一举,但是很不幸,这种注释很常见---通常是用于热心的IDE插入的.最好的状况下.他不过是为代码添加.了“噪音”.最坏的情况下,随着时间的推进这些注释则会过时,变得不在正确.

许多的注解没有传递任何有意义的信息.例如,对于passthorugh()方法它的注释是”这个方法允许你传递”,但是读者能从中的到什么信息呢?这种注释只会分散注意力.而且很容易失去效性[假使方法最后方法有被命名为sendToHost()]注释可以用来为读者指定一条正确的代码访问路线图.为代码中的每类或者模块添加一个短小的描述.说明其中的目的以及是否有任何特别的需求.对于类中的每个方法可能要说明下列信息.

? 目的: 为什么需要这个方法?

? 需求(前置条件):　方法需要什么样的输入，对象必须处于何种状态．才能让这个方法工作．? 承若（后置条件）：　方法成功执行后，对象处于什么样的状态．有那些返回值．? 异常：　可能会发生什么样的问题．会抛出什么样的异常．要感谢如ＲＤｏｃ，ｊａｖａｄｏｃ和ｎｄｏｃ这样的工具，使用他们可以很方便的直接从代码注释创建有用的，格式优美的文档．这些工具抽取注释，并生成样式漂亮且带有超链接的ＨＴＭＬ输出．使用注释沟通：使用细心的选择的，有意义的命名．用只是描述代码的意图和约束．注释不能代替优秀的代码．切身感受　

注释就像是可以帮助你的好朋友，可以先阅读注释，然后快速浏览代码．从而完全理解它做了什么．以及为什么这样做？

平衡的艺术

? ｐａｓｃａｌ定理的创始人Ｂｌａｉｓｅ　Ｐａｓｃａｌ曾说，他总是没有时间写短息．所以只好写长信．请话花时间去写简单扼要的注释吧！

? 在代码可以传递意图的地方不要写注释．? 解释代码做了什么的注释用处不那么大．相反，注释要说明什么为什么会这样写代码．? 当中写方法时，保留描述原有的方法意图和约束的注释．