yusubond / yusubond.github.io Goto Github PK

https://www.emojiall.com/zh-hans

编程习惯

按编程语言

Golang

https://github.com/golang/go/wiki/CodeReviewComments

参考资料

《编写可读性代码的艺术》
《程序员修炼之道-从小工到专家》
https://google.github.io/styleguide/

核心**

本书的核心**就是代码应该写得容易理解，即让别人能用最短的时间理解你的代码。

可读性定理

代码的写法应当使别人理解它的时间最小化，即为可续性定理。

第一部分：表面层次上的改进

原则一：把信息装到名字里

1. 选择专业的词

举例：
"get"这个词就非常不专业，没有表达出很多信息，既可以表示从本地缓存得到一个页面，也可以表示从数据库中，甚至可以表示从互联网中，更专业的词语应该是FetchPage()或DownloadPage()。

def getPage(url): ...

要用于找到更有表现力的词语，例如

2. 避免泛泛的名字

像tmp, retval, foo这样的名字都是"我想不出名字的”托辞，不应该使用这样空洞的名字，应该挑选那些能够描述这个实体的值或目的的名字。举例，下面的例子中用sum比res更好。

var res int
for _, v := range nums {
  res += v
}

像i,j,k等名字常用作索引和迭代器，但是在多层循环中往往可能用错，可以通过增加前缀使其更精确。举例：

for (int i = 0; i < club.size(); i++)
  for (int j = 0; j < club[i].members.size(); j++)
    for (int k = 0; k < users.size(); k++)
      if (club[i].members[k] == users[j])   // 注意，这里有一个错误
        cout << "user[" << j << "] is in club[" << i << "]" << endl;

如果将i, j,k换成ci,mj,uk往往可以避免上面的错误。

3. 用具体名字代替抽象的名字

给变量、函数或者其他元素命名时，要把它描述得更加具体，而不是更抽象。

举例：

我们的一个程序有个可选的命令行标志叫做--run_locally。这个标志会使得这个程序输 出额外的调试信息，但是会运行得更慢。这个标志一般用于在本地机器上测试，例如在 笔记本电脑上。但是当这个程序运行在远程服务器上时，性能是很重要的，因此不会使 用这个标志。

你能看出来为什么会有--run_locally这个名字，但是它有几个问题:

• 团队里的新成员不知道它到底是做什么的，可能在本地运行时使用它(想象一
  下)，但不明白为什么需要它。

• 偶尔，我们在远程运行这个程序时也要输出调试信息。向一个运行在远端的程序传
  递--run_locally看上去很滑稽，而且很让人迷惑。

• 有时我们可能要在本地运行性能测试，这时我们不想让日志把它拖慢，所以我们不会使用--run_locally。

这里的问题是--run_locally是由它所使用的典型环境而得名。用像--extra_logging这样的名字来代换可能会更直接明了。

但是如果--r u n_l o c a l l y需要做比额外日志更多的事情怎么办?例如，假设它需要建立和使用一个特殊的本地数据库。现在--run_locally看上去更吸引人了，因为它可以同时控 制这两种情况。

但这样用的话就变成了因为一个名字含糊婉转而需要选择它，这可能不是一个好主意。 更好的办法是再创建一个标志叫--use_local_database。尽管你现在要用两个标志，但 这两个标志非常明确，不会混淆两个正交的含义，并且你可明确地选择一个。

4. 用前缀或后缀给名字附带更多的信息

一个变量名就像是一个小小的注释。

如果关于一个变量有什么重要的需要读者必须知道，那么是值得把额外的“词”添加到名字中。举例，假设你有一个变量包含一个十六进制字符串：

var id string  // Example "123456789abcde"

如果让读者记住这个ID的格式很重要，那么这个变量名应该是hex_id。

同理，如果你的变量是一个度量的话，那么最好名字中带上它的单位。举例：

var start_ms = (new Date()).getTime(); // top of the page

5. 决定名字的长度

当选择好名字的时候，有一个隐含的约束就是名字不能太长。

可以采用的一些小的直到原则：
1）在小的作用域可以使用短的名字；
2）首字母缩略词和缩写，这条使用的经验原则是团队的新成员是否能够理解这个名字的含义？如果能，那么就没问题。
3）去掉没用的词；举例：ConvertToString()不如ToString()好。

6. 名字的格式表达含义

例如Google的C++代码格式规范Google C++ Style Guide。

原则二：不会误解的名字

小心可能有歧义的名字。

举例，Filter()，filter是个二义性单词，无法清楚地表达是“挑出”还是”减去“，应避免使用这样的单词。

同样的单词还有limit，无法表达出”大于“还是“小于”。**命名极限最清楚的方式就是在要限定的东西前面加上max_或min_。

推荐用first和last来表示包含的范围；用begin和end来表示包含/排除的范围。

对于布尔变量，通常来讲，加上is,has,can或should这样的词，可以把布尔值变得更加明确。

不会误解的名字就是最好的名字——阅读你代码的人应该理解你的本意，并且不会有其他的理解。

原则三：审美与设计

好的源代码应当”看上去养眼“。

在讨论审美和设计的时候，我们所说的是以下三个原则：
1）使用一致的布局，让读者很快习惯这个风格；
2）让相似的代码看上去相似；
3）把相关的代码分组，形成代码块。

重新安排换行来保持一致和紧凑，注释也要对齐。

在需要的时候使用列对齐，列的边提供了“可见的栏杆”，阅读起来方便，这是个“让相似的代码看起来相似的好例子”。

选择一个有意义的顺序，始终一致地使用它。

按声明把块组织起来，不要把所有的方法都放到一个巨大的代码块中，应该按逻辑把它们分组。

核心**就是，一致的风格比“正确”的风格更重要。

具体技巧包括，

• 如果多个代码块做相似的事情，可以让他们有同样的剪影；
• 代码按列对齐，可以让代码更容易浏览；
• 如果在一段代码中提到A，B和C，那么不要在另一段代码中说B，C和A。选择一个有意义的顺序，并始终用这样的顺序；
• 用空行把大块代码分成逻辑上的“段落”。

原则四：什么样的注释

你可能认为注释的目的是“解释代码做什么”，但这只是其中很小一部分。

核心**，注释的目的是尽量帮助读者和作者了解的一样多。

什么地方不需要注释：
1）能从代码本身中迅速地推断的事实；
2）“拐杖式的注释”——试图粉饰可读性查的代码的注释。好代码>坏代码+好注释

应该记录下来的想法包括：
1）对于为什么代码写成这样而不是那样的内在理由，即“指导性批注”；
2）代码中的缺陷，使用像TODO:或XXX:这样的标记；
3）常量背后的故事，为什么是这个值。

站在读者的立场去思考：
1）预料到代码中哪些部分会让读者说：“啊？”，并且给他们加上注释；
2）对普通读者意料之外的行为加上注释；
3）在文件/类的级别上使用“全局观”注释来解释所有的部分是如何一起工作的；
4）用注释来总结代码块，使读者不致迷失在细节中。

如果你要写注释，最好把它写得精确——越明确和细致越好。

注释应当由很高的信息/空间率。

写出言简意赅的注释的一些具体提示：
1）当像"it"，"this"这样的代词可能指代多个事物时，避免使用它们；
2）尽量精确地描述函数的行为；
3）在注释中用精心挑选的输入/输出例子进行说明；
4）声明代码的高层次意图，而非明显的细节；
5）用嵌入的注释来解释难以理解的函数参数；
6）用含义丰富的词来使注释简洁。