代码整洁之道 | Blog of Huiteng

type

status

date

slug

summary

（一）命名

起个名称不能有废话

例如，有了命名为Product类，还定义一个为ProductInfo或ProductData。两者虽然名称不同，意思却无区别。也就是不管有无Info或Data，意思都同指的是Product。此外，名称含有一些a,an,the也纯属是废话。Variable不会出现在变量名中。Table也不应当出现在表名中。像是NameString，CustomerObject都属于废话

使用读得出来的名称使用可搜索的名称

WORK_DAYS_PER_WEEK

类名和对象名应该是名词或名词短语\方法名应当是动词或动词短

给每个抽象概念选一个词，命名应当独一无二

起个getDogName在Dog类里，起个getCatAddr在Cat类里

（二）函数

短小：代码块和缩进

if语句，else语句，while语句等，其中的代码块应该只有一行。改行大抵应该是一个函数调用语句。这样不但能保持函数短小，而且，因为块内调用的函数拥有较具说明性的名称，从而增加了文档上的价值。这也意味着函数不应该大到足以容纳嵌套结构。所以函数的缩进层级不该多于一层或两层。

如果函数只是做了函数名下同一抽象层上的步骤，则函数还是只做了一件事。

向下规则。作者认为函数里应当调用的所有函数都属于同一个抽象层，而函数内调用的函数属于主调用函数的下一个抽象层。

参数：

·一元参数：输入参数命名要明确含义，禁止传布尔参(违反单一函数做一事的原则)

write(name)改为writeField(name)，它告诉我们，“name“是一个”field”。

·二元参数：要注意在函数内声明参数的顺序问题。相关的概念排列靠近在一起。

·如果函数看来需要两个，三个或三个以上参数，就说明其中一些参数应该封装为类了。

Try/catch代码块应当抽离出来，另外形成函数。处理错误的函数应当只做处理错误的这件事，不能参杂有其他事情

命名：驼峰+做什么

（三）注释

①注释的内容意图要明确，清晰简洁，不能含糊不清，不能有废话出现。

②注释掉的代码一定是在将来是会有用处的，没有用的或是用处不大的代码应当清理干净。最好还是尽量不要有注释掉的代码出现。

③要注重代码的规范，代码能解释清楚的，就要尽量减少不必要的注释内容。

④经过修改代码逻辑之后，原先注释掉的解释或者代码不再有价值时，应当及时删除掉，避免自己或后来开发者会在此后去理会这些没有用的注释而浪费时间。

⑤好的注释应当出现在不得不添加的情况下，比如必须要添加法律信息的情况，为代码难以命名的情况，将来一定会补充代码的情况，某处代码块有着严重警示的情况。

有用的注释：

1.法律信息（例如公司代码规范必要时，版权以著作权声明在每个源文件开头注释处放置） 2.提供信息的注释（用来解释不能用名称解释的代码）

3.对意图的注释。（对代码逻辑或放置位置的决定的解释）

4.阐释（用来解释晦涩难懂的参数或返回值）

5.警示（解释某处代码的作用很重要）

6.TODO注释（还差xx，作者不提倡使用这种注释）

（四）对象和数据结构

一些用户无需了解数据的实现不应当出现在实现整块的代码里，而要分清楚哪些是需要隐藏的代码逻辑，哪些是需要显示给用户看的。（同样用户指的也是程序员本身，或者其他人）。

错误处理

（如果总是以if语句来判断错误，代码就会多个if语句，显得代码混乱。有些情况使用抛出异常就会更好些。）

先写Try-Catch-Finally语句

同样的，抛出异常同样的只能做一件事，Try做一件事，Catch处理一件事。如果有多处使用到异常处理，那可能需要专门封装成一个类了

（五）类

组织

如果有公共静态常量，应该先出现。然后是私有静态变量，以及私有实体变量。很少会有公共变量。

公共函数应跟在变量列表之后。我们喜欢把由某个公共函数调用的私有工具函数紧随在该公共函数后面。

短小

类同样要遵守单一权责的规则，只做一件事。

例如，把行为相关的封装成类，把数据相关的封装成类，修改一个地方要么是行为，要么是对数据的修改。尽量不在一个类里既可以修改行为，有可以修改数据。

另外，描述一个类，不用”if”，”and”，”or”,”but”这些词汇作为类名的一部分，否则这显得类不仅仅只做一件事了。

内聚

如果一个类中的每个变量都被每个方法所使用，则该类具有最大的内聚性。创建这种极大化内聚类是既不可取也不可能的。我们希望内聚性要尽量保持在较高位置。

如果类丧失了内聚性，就要拆分它为几个新的类。

只做一件事的类过长时，该如何做？

如果类里有很多相关并且内聚性较高的变量和方法，也应当分类拆离出新的文件。例如，一个文件负责做初始化工作，另一个文件负责做功能操作。

🤠代码整洁之道

（一）命名

（二）函数

（三）注释

（四）对象和数据结构

（五）类