《编程匠艺》读书笔记之二

第三章 名正言顺

• 远古的人认为命名某个事物就是对其拥有权利。这不仅仅是简单的宣称所有权。一些人对名字的力量坚信不疑，以至于他们从不将自己的名字告诉陌生人，因为他们害怕陌生人会使用名字来伤害他。
• 名字所描述的内容包括：1. 身份；2. 行为；3. 识别，名字将一个事物标明为一个性质独特的实体。
• 我们为什么应当恰当的命名呢？因为编写源代码就是关于如何进行清晰的交流，恰当的命名意味着“了解名称就可以了解对象”。
• 清晰的命名是优秀代码的特点之一，一个对象的名称应该清晰的描述了这个对象。
• 在编码时，需要进行命名的内容包括：1. 变量；2. 函数；3. 类型； 4. 命名空间或者包的名字；5. 宏； 6. 源文件名称。
• 为了恰当的命名，在为一个对象想出名称以前，必须准确的了解这个对象是什么，如果你不知道你所命名的对象是什么，它的用途和它存在的理由，你怎么能够赋予它一个有意义的名字呢？所以说糟糕的名称通常表明你对需要命名的对象缺乏理解。
  
  一个好的名称具有以下特点：
• 技术上正确。符合所使用的语言在命名上的限制。
• 符合语言习惯。要了解你的语言的命名规则，更重要的是，了解这种语言的习惯用法，公共命名约定是什么？应用这些语言习惯和约定。
• 恰当。包括以下几点：1. 长度，在进行命名是，将重点放在清晰而非简洁上，慎用各种奇怪的所写；2. 格调，一般在命名时不要使用语气助词。
• 理解在较短的名称和较长的名称之间进行权衡的考虑因素，即它们是如何依赖于变量的作用范围的，对于循环计数器这种变量，就可以简单的以i来命名，但是要注意在多重循环时，最好起一个易理解的名字。
  
  如何命名一个变量：
• 一般情况，变量用一个名词来表示。
• 如何不是名词，通常会是一个名词化的动词。
• 有很多用于修饰成员变量的面向对象的语言约定，以说明它们是成员，而不是局部变量或者全局变量。
• 一种常见的命名习惯是使用首字母缩略词作为简洁和“有意义”的名称，例如：我们可以这样声明一个变量：SomeTypeWithMeaningfulNaming stwmn(10);
• 一般情况下，将类姓名和变量名区分开，类姓名通常都有一个大写的首字母，而变量名则具有小写的首字母，例如：我们可以这样声明一个变量：Window window;
  
  如何命名函数：
• 如果变量像一件可以握在手里的东西，那么函数就是你拿这件东西所做的事，它的名字在逻辑上更应该是一个动词。
• 有意义的函数名字应该避免使用be、do和perform等词语。
• 我们应该隐藏函数内部的具体实现过程，始终从使用者的角度来为函数命名。但是当在为请求信息的简单查询函数进行命名的时候，可以不必遵守。
• 当你编写一个函数时，应该使这个函数很好的文档化，其名称应该仍然是关于函数用途的一个清晰的描述，这是函数契约的一部分。
  
  如何命名类型：
• 对类的命名没有太多严格的直觉推理法，因为不同的类有不同的用途。
• 在名称中避免使用多余的词，尤其实在类型名中避免使用以下这些词语：class、data、object和type。
• 要确保你描述的数据的类不是一个真正的对象。
• 糟糕的类名会使程序员们感到困惑，较好的命名能为代码的逻辑提供清晰的思路。
  
  如何命名名字空间：
• 选择描述其内容的关系的词语。
• 不要选择重复暗示命名对象是一个集合的名称，例如：controls_group就不是一个好的名称。
  
  如何命名宏：
• 名字全部使用大写字母。
• 不要为其他任何对象使用这种全部大写的名称。
  
  如何命名文件：
• 注意大小写，一些文件系统不区分大小写。
• 确保同一目录中的文件名不仅仅只是大小写不同。
• 尽量保证你创建的文件都具有不同的名称，即使这些文件都分布在不同的目录中。
  
  一个好的名字，具有以下特点：
• 保持前后一致，命名一致不仅限于创建名称时的大小写和格式化，一个名称将确立一个隐喻，在这个程序中，这写隐喻应该保持一致。
• 利用代码的内容，我们要充分利用上下文，写出简洁的、描述性的以及没有多余信息的名称。
• 使用对你有利的名字。
  
  一个好的名字，不应该具有的特点：
• 含义模糊。
• 啰嗦。
• 不准确或使人误解。
• 有歧义或者含糊不清。
• 太做作。
• 优秀的程序员：1. 意识到名字的重要性并尊重它们；2. 为他们创建的所有对象都考虑如何进行命名，并且选择恰当的名称；3. 使许多考虑因素保持平衡，包括名字的长度、清晰度、上下文等；4. 从整体的视角来命名，因此他们的名称在一个项目中都保持一致。
• 糟糕的程序员：1. 不关心他们的代码是否清晰；2. 很快的编写代码而很少进行思考；3. 忽视语言的自然习惯；4. 命名时前后不一致；5. 不从整体的角度进行思考，不考虑他们的代码怎样和整体相结合。
• 在许多不同的上下文中，重复使用同一个局部变量名是完全可以接受的。
• 不要用局部变量名隐藏全局变量名，这样容易造成混淆。
• 优秀的编码高手会把良好的命名当做一种习惯，而且不需要编码规范来“约束”。

第四章 不言自明

• 创建优秀的代码以为着创建良好文档化了的代码。
• 编写代码是一件艰苦的工作，将代码文档化更是艰苦异常。
• 就像代码一样，文档必须接受版本控制，你必须要确保你阅读的文档的版本和你正在处理的代码的版本保持一致。
• 唯一能够完整并正确的描述代码的文档就是代码本身。这并不自然而然的以为着代码本身就是最佳的描述，但是在通常的情况下，这是你能够获得的唯一文档。
• 编程语言是我们交流的媒介，清晰地交流至关重要。清晰的代码会活的较高的质量，因为你犯错误的可能性降低了，而且这样的代码维护的成本也比较低。
• 自文档化的代码有很高的可读性。
  
  如何编写自文档化的代码：
• 使用好的样式编写简单的代码。1. 让“正常”的流程明显的贯穿你的代码，错误的情况不应该扰乱程序的正常执行流程；2. 避免过多的使用嵌套语句；3. 要谨慎的优化代码，如果一定要优化，那么要清晰的注册这段代码发生了哪些变化。
• 选择有意义的名字。好的名字也许是我们避免多余注释的最好办法。
• 分解为原子函数。1. 一个函数，一种操作；2. 减少任何出人意料的副作用；3. 保持简短，短小的函数易于理解。
• 选择描述性的类型。
• 命名常量。避免在程序中进行“硬编码”，避免使用神奇数字。
• 强调重要的代码。1.在类中按一定顺序进行声明；2. 尽可能隐藏所有不重要的信息；3. 不要隐藏重要的代码；4. 限制嵌套的条件语句的数量。要确保所有重要的代码非常突出，并且易于阅读，将任何目标读者不关心的内容都隐藏起来。
• 分组相关信息。
• 提供文件头。在文件的顶部放置一个注释块，以描述文件的内容以及该文件所属的项目。
• 恰当的处理错误。在最恰当的上下文中处理错误，不要返回无意义的错误。
• 编写有意义的注释。清晰的代码应该包含“适量”的注释（“适量”：只有在你无法以任何其他方式来提高代码清晰度的情况下，再添加注释）。
  
  实现自文档化的方法：
• 文学性编程。你不是在编写程序，你是在编写文档。源代码就是文档。高质量的文档永远都取决于编写策划那个徐的程序员。文学性编程实际上是带有设计的传统代码与实现规范这两者的结合。
• 文档化工具。例如JavaDoc和NDoc。
• 写作的技巧就是创建一个上下文环境，别人在其中思考。
• 优秀的程序员：1.努力编写清晰、自文档化的代码；2. 尽量编写所需的最小量的文档；3. 考虑哪些需要维护其代码的程序远门的需求。
• 糟糕的程序员：1. 对于他们所编写的难以理解的代码非常骄傲；2. 尽力避免编写各种文档；3. 不关心更新文档的问题；4. 认为：如果我写起来很困难，那么别人理解起来也会很困难。
• 如何将相关代码进行分组，一般有以下几种方法：1. 名称前缀或后缀；2. 文件系统中的位置；3. 将相关内容放置到一个类中或者结构中。
• 如果有良好的代码文档，那么一个新手就应该很清楚代码中的某个部分有什么作用。
• 编码规范或者编码风格虽然有一定作用，但是没有什么可以取代精明、合理的编程。愚蠢的程序员即使遵守最严格的标准，也仍然会写出很差的代码。