日期:2022年3月16日标签:DeveloperHandbook

写给自己的代码整洁之道 #

有意义的命名 #

  • 名副其实:变量、函数或类的名称应该已经答复了所有的大问题,它该告诉你,它为什么存在,做了什么事,应该怎么用。
  • 避免误导:避免使用与本意相悖的词。
  • 有意义的区分:名称不应该类似,要做有意义的区分,避免使用 a1、a2 这样的类似名称。
  • 使用读得出来的名称:命名时要使用正确的英文单词,尽量避免使用不好理解的缩写或者错词。
  • 使用可搜索的名称:避免使用单字母和数字名称,使名称易于搜索。
  • 避免使用编码:编码会增加解码的负担,而且不便发音,容易打错。
  • 类名:类通常是一个对象,所以应该用名词或者名词短语。
  • 方法名:方法表示的是一个操作,所以应该用动词或者动词短语。
  • 每个概念对应一个词:同一个项目中,同一个概念应该用同一个词,比如 get 和 fetch 都可以表示“取”的意思,但是在同一项目中,应该始终使用同一个词表示“取”这个概念。
  • 一词一义:同一个词只表示一个意思,不应该出现一词两义或者多义。
  • 使用专业名词:如果项目涉及某个业务,尽量使用与业务相关的词语。

函数 #

  • 短小:函数的第一规则是要短小。第二条规则是还要更短小。
  • 只做一件事:应该遵循单一职责原则,一个函数只做一件事。
  • 使用描述性的名称:名称应该能描述这个函数做了什么事。
  • 函数参数:参数应该尽量少,最好维持在三个以内。
  • 无副作用:函数应只做一件事,避免有其他副作用。
  • 避免重复:避免写重复代码。
  • 结构化编程:尽量保证每个函数、函数中的每个代码块都应该只有一个入口、一个出口。

注释 #

如果注释使代码更糟糕,那么应该删除注释。

  • 注释不能美化糟糕的代码:写注释的常见动机之一是糟糕的代码的存在,带有少量注释的整洁而有表达力的代码,要比带有大量注释的零碎而复杂的代码像样得多。
  • 用代码代替注释:好的命名通常比注释更有用。

格式 #

  • 自顶向下:源文件最顶部应该给出高层次概念和算法。细节应该往下渐次展开,直至找到源文件中最底层的函数和细节。
  • 函数之间用空行隔开。
  • 行宽:一行代码的字符不要超过150个。
  • 缩进:保证代码缩进正确,水平对齐。
  • 团队规则:一切以团队规则为准则。

#

  • 类中成员从上至下的分布顺序:
1. 公有静态常量
2. 私有静态变量
3. 公有普通变量
4. 私有普通变量
5. 公共函数
6. 私有函数
  • 不过多暴露类的细节:尽量保持函数和变量的私有
  • 单一职责原则:类的功能应该单一。
  • 高内聚性:类中方法和变量相互以来,形成一个逻辑整体。
  • 面向接口编程:类应该依赖于抽象,而不是依赖于具体细节。使类更加灵活可复用。

参考 #

(完)

目录