Javascript模式阅读笔记 · 基本技巧（三）
编写注释
为代码编写注释是非常重要的，甚至在该代码除您之外其他人都不会接触到时都需要编写注释。通常人们在深入思考一个问题时，会非常清楚这段代码的工作原理。但是当过一周后再次回到该代码时，可能会花上很长时间来回想起那段代码到底是干什么的。
不需要注释一些比较明显的代码：例如每一个变量或每一行都注释。但通过有必要对所有的函数、函数参数、返回值、其他有趣或不同寻常的算法和技术都用文档记录下来。设想注释就是未来代码阅读者的一个提示，只需要阅读注释就能明白代码中有哪些函数和属性名。举例来说，当有一段5至6行的代码执行了一个具体的工作，如果有一行描述该代码功能并说明为什么代码位于本位置的注释，那么阅读者就可以忽略代码的细节。关于代码注释没有严格不变的规则和比例，有一些代码（例如正则表达式）可能实际上注释会比代码长度更长。
注意：最重要的习惯，也是最难遵循的习惯就是不断更新注释，因为过期的注释可能会误导阅读者，这比没有注释更可怕。
编写API文档
大多数开发者认为编写文档是一件令人烦厌的不值得去做的任务。但事实并非如此，API文档可以从代码的注释中自动生成，通过这种方法实际上都无需编写就可以自动获得文档。大多数程序员认为这种想法是有极大吸引力的，因为从特定关键字和特定格式化的“命令”来自动生成可读的文档看起来很像一种编程操作。
传统的API文档最早来自Java语言中，在Java SDK（软件开发工具集）中发布了一个名为javadoc工具。很多其他语言也开始采纳了这个思想。在JavaScript中有两个优秀的工具，这两个工具都是免费并且开源的，分别是JSDoc Toolkit和YUI Doc。
生成API文档的步骤如下：
1. 编写特殊格式块代码。
2. 运行工具来解析代码和注释。
3. 发布工具解析的结果，大多数情况下采用HTML格式发布。
编写可读性强的代码
为API编写注释不仅仅是一种提供参考文档的简便方法，而且还有其他用途——通过再次审视代码，提高代码质量。
几乎所有的作者和编辑都会告诉您编辑校对工作十分重要的：这有可能是出版优秀书籍和文章的最重要的步骤。将最初的草稿内容写到纸上仅仅是第一步。草稿会传递一些信息给读者，但是这些信息可能不十分清晰、结构性不好，并且不好理解。
编写代码也是类似的。当您坐下来解决问题时写出的解决方案仅仅是一个初稿。该解决方案可以给出令人期待的输出，但是该方案是否是最佳方案呢？该代码是否可读、易于理解、维护和升级呢？当您再次审视代码时，您将更加确定代码哪些部分可以改进——如何使得代码更容易继续更新、移除一些不足之处等。这就是编辑校对工作的重要性，它可以极大地帮助您创建高质量的代码。但是通常任务都是时间期限很紧张，没有更多的时间用于编辑校对（这的确是一个问题，实际情况可能是昨天就需要将工作提交）。这也就是为什么编写API文档是编辑校对的一个机会。
通常在编写文档注释时，会重新思考一些问题。有时候反省可以使得代码更清晰。举例来说，有些代码的方法的第三个参数使用比第二个参数频繁得多，并且第二个参数通常默认值是true，那么就可以调整该方法的接口，交换第二个和第三个参数。
编写可读性强的代码意味着在编写代码，甚至仅仅是编写某个API时，心里都要想着该代码可能是要提供给其他人阅读的。这种思维方式将有助于编辑校对和思考更好的解决问题的方法。
谈论到初稿时，还有一个“未雨绸缪”的观念。看起来有一些极端，但是这是十分有意义的，特别是当手头上有一些关键任务项目时（人们的生活依赖于此）。这个观念是您想出来的第一个解决方案可能可以解决问题，但是这不过是一个草稿，是解决问题的方法之一。第二个解决方法通常要更好，因为这是对问题的理解会更深入。在第二个解决方案中，不允许直接从第一个方案中复制、粘帖出来，这样可以阻止为了简便而满足于不完美的解决方案。
同行互查
另外一种优化代码的方式是采取同行互查的方式。同行互查可以采用正式和标准化的途径，甚至是采用一些专用的工具。将同行互查作为开发过程中流水化的一部是十分重要的。在如果没有足够时间来研究和采用审查工具时，也要坚持同行互查。这种情形下，可以简单地走到隔壁，请坐在那里的开发者看一下您的代码。
和使用API文档或其他类型文档一样，同行互查的方式有助于编写更为清晰的代码。这里的原因在于其他人需要阅读和理解才能明白您的代码具体是用于做什么事情的。
同行互查是一种非常好的实践方法，不仅仅是因为这样做可以得到更好的代码，而且通过这样做可以使得审查人和代码编写者可以交换和共享知识，进而学习到对方的经验和独有的方法。
如果您是一个单干者，并没有同行来审查代码，这也不应该成为障碍。可以将代码中的一部分开源，并将代码中有趣的片段放置在博客中，那么全世界的人都可以成为您的审查员。
另外一个比较好的实践方法是使用源码控制系统（例如CVS、Subversion和Git），这些系统会在有人更新代码后自动向项目团队发送邮件。大部分这些邮件是不会有人阅读的，但是有些时候某个同时可能想从自己的工作中休息一下，并自发地看看您刚提交的代码。
在正式发布时精简代码
可以采用减少空白位置、注释和其他JavaScript代码中不重要的部分来减小需要从服务器端传输给浏览器的JavaScript文件，以便加速页面载入速度。通常该工作是采用工具来实现的（例如 Yahoo的YUICompress 或 Google的Closure Compiler）。在正式发布之前精简脚本是非常重要的，因为这样做的结果可以大大缩小JavaScript文件，通常可以减少一半左右。
除了除去空格、新的空行、注释以外，精简器还会将变量重新命名为一个较短的名称（当然是保证安全的前提下），例如在处理过后的代码中用A.B.C.D来表示变量。精简器只会重命名局部变量，因为重命名全局变量可能会破坏代码。这也是为什么要尽量多使用局部变量的原因。如果在函数中多次使用了全局变量，例如DOM引用，最好是将其分配给一个局部变量。这将加速解析变量名的速度，以便在精简以后运行速度更快，下载速度更快。
备注一下，Goolge的Closure Compiler也会尝试重命名全局变量（在高级模式中），如果确定要利用该功能附加精简功能，请务必意识到这样做具有一定风险，需要特别注意。
精简发布版本代码是十分重要的，因为这将有助于提升页面的性能，但是应该将这部分工作留给精简器来做。尝试手工编写精简的代码是错误的。在编写代码的时候仍然要使用有含义的变量名、一致性的空格和指示符、注释等。这样边写出来的代码可读性强，以便使得维护者能够快速的理解代码，并让精简其来精简文件大小。
