详细总结《代码整洁之道》 - 基础篇

 

本文概述

本文详细总结了本书《代码整洁之道》前文部分的知识点。梳理的具体内容如下：命名规范需要注意的地方；如何编写函数里的代码以及函数之间放置的位置；注释需要注意的地方，代码格式以及在某些情况下需要处理异常。

本文属于基础篇，也是在我们编程工作中经常涉及到的内容。至于本书后部分内容，如测试代码部分，系统设计的规则，以及重构部分，暂不继续进行做个笔记。此后如若有时间的允许下，我就会继续总结下部分内容。若条件不允许，则不会继续写下去了。

“下划线”代表的是本书部分的原文内容。

写于2021年2月21日

正文

 

 

（一）有意义的命名

 

名副其实

给变量，函数或类要起个与它本身含义相符合的名称。如果一旦发现有更好的名称，就换掉旧的。

 

避免误导

程序员应当避免使用与本意相悖的词。

 

①不能起个与某平台的专有名称相同的名称。

例如，hp,aix和sco都不该用做变量名，因为它们都是UNIX平台或类UNIX平台的专有名称。

 

②别使用对程序员有特殊意义的词。

例如，别用accountList来指称一组账号，除非它真的是List类型。如果包纳账号的容器并非是个List，就会引起错误的判断。建议使用accountGroup，甚至直接用accounts都会好一些。

 

③提防使用不同之处较小的名称。指的是提防使用一组单词外形相似，却无法快速区分开来的名称。

例如，XYZControllerForEfficientHandlingOfStrings 和

XYZControllerForEfficientStrorageOfStrings。由于不同意思的两者外形太相似，则我们需要花点时间才能理解。

 

④以同样的方式拼写同样的概念才是信息。拼写前后不一致就是误导。

⑴相似的名称依字母顺序放在一起，且差异很明显，就会有助于理解。

例如，ScaleX，ScaleY，ScaleZ，把它们放在一起。

 

⑵误导性名称，也有与其他概念混在一起交叉式使用。

例如代码：

int a=1;
if(o==1)
    a=01;
else
    l=01;

其中很难看得出o和l是字母还是数字。

 

做有意义的区分

在同一作用范围内两样或两样以上不同含义的对象重名的情况下，则需要修改其中一个的名称。

①不能干脆以错误的拼写充数。

例如，同一作用范围里，有两个重名的Scale变量。如果随意修改其中一个为Scael，即便编译器通过，也会使编译器出错。

 

②不能以数字系列依义的对立面来命名，这会造成误导。因为完全没有提供正确信息，也就是没有提供代码个体之间的具体含义。

例如：

copy(char a1[],char a2[])改为copy(char source[],char destination[])，就会像样许多。

 

③起个名称不能有废话。

不要使用一些与对象毫无影响的词。

例如，有了命名为Product类，还定义一个为ProductInfo或ProductData。两者虽然名称不同，意思却无区别。也就是不管有无Info或Data，意思都同指的是Product。此外，名称含有一些a,an,the也纯属是废话。

从类型方面来讲：

Variable不会出现在变量名中。Table也不应当出现在表名中。像是NameString，CustomerObject都属于废话。

 

使用读得出来的名称

要使用读得出来的名称，而不要使用把一组单词严重缩写的名称。

例如，genymdhms(生成日期，年，月，日，时，分，秒)，应改为generation timestamp。

 

使用可搜索的名称

若变量或常量可能在代码中多处使用，则应赋其以便于搜索的名称。

例如，WORK_DAYS_PER_WEEK这个常量会在代码中多处使用到，搜索与其相关的代码逻辑时，会比数字5好找。

 

有争议性的命名法

匈牙利语标记法

匈牙利语标记法的特征便是：名称的前字母描述了该变量的类型，例如bChecked以b开头的变量代表是一个布尔类型的。但是这个标记法是有争议性的，是否被采用，得根据程序员本身使用的习惯或适用于某种情况。

不过本书作者为代码起名称时，不提倡匈牙利语标记法。因为作者认为带有类型标记的字母也纯属是废话。

而我认为这种标记法更多使用在C/C++方面上，尤其涉及到多个复杂的指针时，带有指针类型字母的变量会让人更快地知道这是个什么样的指针变量。至于C#，可能没有多大的影响，例如bChecked可以改成isChecked会更好些。例如chName不如Name好，因为在代码的约定中，Name除了字符串类型之外，不太可能会是一个诸如int的其他类型。

成员前缀

以m_开头来表明成员变量，通常会在老代码中出现。例如在MFC中，封装类里的成员变量就是以m_开头的。反正作者也不喜欢这种命名的方法。尽管在以前的代码中常常出现，但是现在的编译环境大有改进，可以直接把光标停在变量的位置，编辑