随笔八：风格指南与规则

管理代码库的规则：关于源文件存储位置的规则、关于代码风格的规则、关于命名、模式、异常、线程的规则。

 

规则就是法律，他们不仅仅是建议或者提示，而是严格的强制性法律。

这些规则是普遍可支持的，除非在必要使用的基础上获得批准，否则不得与易忽视。

指南提供了建议和最佳做法。

 

为什么要有规则？

　　制定规则的目的是鼓励好的行为和劝阻坏的行为。

　　随着一个组织的发展，既定的规则和指导方针形成了编码的通用词汇表。

 

创建规则

　　在定义一套规则时，关键问题不是“我们应该拥有那些规则？”我们要问的问题是“我们要达成什么目标”。当我们关注规则所服务的目标时，识别哪些规则支持这个目标，可以更容易的提取一组有用的规则。

　　我们不问“风格指南包含什么？”而是问“为什么有些东西包含到风格指南中？”“通过指定一套规则来规范代码的编写，我们的组织获得了什么好处？”。

　　指导原则

　　　　瓜拉尼号开发环境的复杂性，保持代码库的可管理型，同时保证工程师高效的工作：

• • • 发挥规则的作用
    • 为读者优化
    • 保持一致性
    • 比卖你容易出错和出人意料的构建
    • 必要的时候要服从实际情况

 

　　规则必须发货其作用

　　　　并不是所有的东西都要放到风格指南里。

　　　　要求组织中的所有工程师学习并使用任何设置的新规则，这些都需要成本。

　　　　如果规则过多，工程师很难记住所有规则，而且会让新来的工程师学习这些规则的难度更高。

　　　　更多的规则也使得维护规则的继承更具有挑战性，维护成本更高。

　　为读者优化

　　·　　伪代码的读者优化，而不是为作者优化。

　　　　考虑到时间的推移，我们的代码被阅读的频率远高于它被修改的频率。

　　　　作为重要的一部分，我们还要求工程师在代码中留下明确的预期行为证据。

　　　　当出现意想不到的情况下，预期行为的证据就变得更加重要了。

　　保持一致性

　　　　一致性使任何工程师即使进入代码库中不熟悉的部分，也能相当迅速的开始工作。

　　　　一个本地项目可以有其独特的个性，但其工具时相同的，技术时相同的，库也是相同的，而且都可以很好的工作。

　　一致性的好处

• • 当代码库的风格和规范在内部保持一致时，编写代码工程师和其他阅读代码的人，可以更关注代码要完成什么，而不是代码的呈现方式。
  • 一致性时对规模化的有力支持。工具是组织扩展的关键，代码的一致性是的构建哪些能够理解、编辑和生成代码的工具变得更容易。
  • 一致性有助于扩展组织的人力。
  • 一致性还确保了对时间的适应能力

　　避免容易出错和出乎意料的构件

　　　　复杂的功能往往有一些微妙的陷阱，乍一看并不明显，在不彻底了解它们的复杂性的时候使用这些特性，容易因误用而引入错误。

　　切合实际

　　　　“愚蠢的一致性是人类思想的妖怪”。在我们寻找一致的、简化的代码库的过程中，我们并不想盲目的忽略其他方面。

　　　　必要时我们允许对可能于规则冲突的优化和实用性让步。

　　　　性能很重要，有时，即使这意味着牺牲一致性或可读性。

　　　　互操作性也很重要。

 

风格指南

• 避免危险的规则
• 执行最佳实践的规则
• 确保一致性的规则

　　避免危险

　　　　我们特别包含了难以使用的和难以正确使用的语言特性的规则，因为这些语言特定具有微妙的使用模式，可能不直观或者不容易正确应用。

　　执行最佳实践

　　　　我们的让风格指南包括了一些要求强制一些强制执行的编码最佳实践的规则。

　　　　何时以及如何使用垂直和水平空白一提供可读性。

　　　　对新的和尚未被理解的语言特性的限制。

　　构建一致性

　　　　我们的风格指南也包含很多小东西的规则。

　　　　明明约定、缩进间距、导入模块顺序之类的问题。

　　　　一种形式比另一种形式相比，通常没有明确的、可测量的、技术上的好处，这可能就是我i什么技术界倾向于不断都它们进行辩论的原因。

　　　　

修改规则

　　我们的风格指南不是静态的。

　　我们的风格指南中，规则背后的决定是有证据支持的。

　　记录下某个具体决策背后的推理，使我们能够识别何时事情需要改变。

　　流程

　　　　我们需要创建一个更新规则的流程，已让我们认识到事情需要改变。

　　　　风格指南更新的提议是基于一个流程图，它首先确定一个已存在的问题，然后提出修改它的方法。

　　　　风格指南的修改建议可能是一个具体且已经更新好措辞的完整建议，也可能是对某一规则的适用性提出的一个模糊问题。

 

风格仲裁者

　　对于每种语言的风格指南，最终的决定换个批准都是由风格指南的所有者，即风格仲裁者做出的。

　　改变不是根据个人喜好，而是权衡取舍。

 

例外情况

　　我们的规则通常是针对更大的一般情况而设计的。有时特定的情况将受益于特定规则的豁免。

　　当出现这种情况时，将咨询风格仲裁者，以确定是否存在特定规则豁免的有效案例。

 

指南

　　指南代表了我们工程经验的智慧，记录了我们一路上从经验中学到的最佳实践。

• • 对于哪些通常很难正确处理的领域，提供特定语言的建议
  • 语言的新特性额详细分类，以及如何在代码库中使用这些特定
  • 库提供的关键抽象和数据结构的列表。

 

应用规则

　　从本质上将讲，规则当它们被强制执行时，就会产生更大的价值。

　　规则可以通过教学和培训这些社会性方式实施，也可以通过工具的技术手段实施。

　　自动化的规则执行确保了规则不会随着时间的推移或组织的扩大而丢失。

　　自动执行的另一个优点是讲规则解释和应用的差异最小化。

　　工具还使实施具有可伸缩性。

　　还有一些规则是社会性的而不是技术性的，用技术性的解决方案来解决社会性问题往往是不明智的。

 

错误检查工具　　　　　　

　　许多涉及语言使用的规则可以通过静态分析工具强制执行。

　　我们使用的工具是为支持我们定义的规则而设计和定制的。

 

代码格式化工具

　　使用自动化风格检查和格式化代码工具在代码中强制执行一致的格式。