CleanCode.md

Clean Code

目的

• 编写代码的难度，取决于周边代码的阅读难度。想要快速实现需求，想要快速完成任务，想要轻松的写代码，请先让你书写的代码整洁易读。
• 保持整洁的习惯，发现脏代码就要及时纠正。花时间保持代码代码整洁，这不但有关效率，还有关项目的生存。
• 程序员遵从不了解混乱风险的产品经理(策划)的意愿，都是不专业的做法。
• 让代码比你来时更干净：如果每次签入时，代码都比签出时干净，那么代码就不会腐坏。
• 赶上期限的唯一方法，做得更快的唯一方法，就是在始终尽可能保持代码的整洁。

命名法则

• 要点一：要名副其实。一个好的变量、函数或类的名称应该已经答复了所有的大问题。一个好名称可以大概告诉你这个名称所代表的内容，为什么会存在，做了什么事情，应该如何用等。
• 要点二：要避免误导。我们应该避免留下隐藏代码本意的错误线索，也应该避免使用与本意相悖的词。
• 要点三：尽量做有意义的区分。尽量避免使用数字系列命名（a1、a2…….aN）和没有意义的区分。
• 要点四：尽量使用读得出来的名称。如名称读不出来，讨论的时候会不方便且很尴尬。
• 要点五：尽量使用可搜索的名称。名称长短应与其作用域大小相对应，若变量或常量可能在代码中多处使用，应赋予其以便于搜索的名称。
• 要点六：取名不要绕弯子。取名要直白，要直截了当，明确就是王道。
• 要点七：类名尽量用名词。类名尽量用名词或名词短语，最好不要是动词。
• 要点八：方法名尽量用动词。方法名尽量用动词或动词短语。
• 要点九：每个概念对应一词，并一以贯之。对于那些会用到你代码的程序员，一以贯之的命名法简直就是天降福音。
• 要点十：通俗易懂。应尽力写出易于理解的变量名，要把代码写得让别人能一目了然，而不必让人去非常费力地去揣摩其含义。
• 要点十一：尽情使用解决方案领域专业术语。尽管去用那些计算机科学领域的专业术语、算法名、模式名、数学术语。
• 要点十二：要添加有意义的语境。需要用有良好命名的类，函数或名称空间来放置名称，给读者提供语境。若没能提供放置的地方，还可以给名称添加前缀。

函数

• 第一原则：短小。若没有特殊情况，最好将单个函数控制在十行以内。
• 第二原则：单一职责。函数应该只做一件事情。只做一件事，做好这件事。
• 第三原则：命名合适且具描述性。长而具有描述性的名称，比短而令人费解的名称好。当然，如果短的名称已经足够说明问题，还是越短越好。
• 第四原则：参数尽可能少。最理想的函数参数形态是零参数，其次是单参数，再次是双参数，应尽量避免三参数及以上参数的函数，有足够的理由才能用三个以上参数。
• 第五原则：尽力避免重复。重复的代码会导致模块的臃肿，整个模块的可读性可能会应该重复的消除而得到提升。

注释

• 第一原则：注释不能美化代码
• 第二原则：尽可能通过代码阐述逻辑
• 第三原则：注释是程序员最无奈的选择，在自己糟糕的代码逻辑上加以修饰，使之看上去还过得去
• 第四原则：法律信息、警示、TODO此类不是对代码进行逻辑解释的注释可以存在

格式准则

整洁代码的书写格式，可以遵从如下几个原则：

• 第一原则：像报纸一样一目了然。优秀的源文件也要像报纸文章一样，名称应当简单并且一目了然，名称本身应该足够告诉我们是否在正确的模块中。源文件最顶部应该给出高层次概念和算法。细节应该往下渐次展开，直至找到源文件中最底层的函数和细节。
• 第二原则：恰如其分的注释。带有少量注释的整洁而有力的代码，比带有大量注释的零碎而复杂的代码更加优秀。
• 第三原则：合适的单文件行数。尽可能用几百行以内的单文件来构造出出色的系统，因为短文件通常比长文件更易于理解。
• 第四原则：合理地利用空白行。在每个命名空间、类、函数之间，都需用空白行隔开。
• 第五原则：让紧密相关的代码相互靠近。靠近的代码行暗示着他们之间的紧密联系。所以，紧密相关的代码应该相互靠近。
• 第六原则：基于关联的代码分布。
  • 变量的声明应尽可能靠近其使用位置。
  • 循环中的控制变量应该在循环语句中声明。
  • 短函数中的本地变量应当在函数的顶部声明。
  • 对于某些长函数，变量也可以在某代码块的顶部，或在循环之前声明。
  • 实体变量应当在类的顶部声明。
  • 若某个函数调用了另一个，就应该把它们放到一起，而且调用者应该尽量放到被调用者上面。
  • 概念相关的代码应该放到一起。相关性越强，则彼此之间的距离就该越短。
• 第七原则：团队遵从同一套代码规范。一个好的团队应当约定与遵从一套代码规范，并且每个成员都应当采用此风格。

对象和数据结构

• 第一原则：迪米特原则，不要跟陌生人说话，对象之间保持应有的私密性

错误处理

• 第一原则：使用异常而非返回码，应该抛出异常信息，而不是返回错误码
• 第二原则：使用未检异常，因为已检异常会破坏开闭原则；C#等没有已检异常
• 第三原则：别返回、别传递NULL

边界

• 第一原则：使用三方库时进行二次封装，对自己的项目只暴露出必要的功能，即：适配器模式
• 第二原则：进行学习性测试

单元测试

• 第一原则：快速，测试应该尽可能快速
• 第二原则：独立，功能测试之间独立
• 第三原则：可重复，测试应该在任何环境下都能通过
• 第四原则：自足验证，测试应有相应的布尔值输出
• 第五原则：及时，功能模块应该及时编写测试，不要积累

类

• 原则一：合理地分布类中的代码。 类中代码的分布顺序大致是：

  1. 公有静态常量

  1. 私有静态变量

  1. 公有普通变量

  1. 私有普通变量

  1. 公共函数

  1. 私有函数

• 原则二：尽可能地保持类的封装。尽可能使函数或变量保持私有，不对外暴露太多细节。

• 原则三：类应该短小，尽量保持单一权责原则。类或模块应有且只有一条加以修改的理由。

• 原则四：合理提高类的内聚性。我们希望类的内聚性保持在较高的水平。内聚性高，表示类中方法和变量相互依赖，相互结合成一个逻辑整体。

• 原则五：有效地隔离修改。类应该依赖于抽象，而不是依赖于具体细节。尽量对设计解耦，做好系统中的元素的相互隔离，做到更加灵活与可复用。