2022-10-15-整洁代码的注释与格式

继续读《代码整洁之道》。

注释

认为写注释就表示一种失败，因为你的代码让人不明白，才需要注释，某种程度上来说也不无道理。

代码会有修改，但注释却不一定及时维护，时间越长，注释和实际情况的差别就可能越大。

通过一个与注释意义相同的函数来代替注释，比如

// Check to see if the employee is eligible for full benefits 
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))

不如改成

if (employee.isEligibleForFullBenefits())

作者也列出一些需要用注释的情况，不过原则还是尽量用代码本身去表明准确的意图。如果要写，注释要精确，一定要真有用，如果根本就不需要看这注释，就不要为了添加注释而加注释

“直接把代码注释掉是令人讨厌的做法”，实际项目中，我倒是经常会这么干，因为项目经常会有调整，有时候这样做，有时候那样做，所以不想将旧的删除，因为后面还会用到。通过版本管理工具去看旧代码，理论是这样，虽然 Git 能看到过去的代码，但是真想用，那么多提交历史，要一个一个看，是哪次修改动的这块代码，实在浪费时间。

注释里写 html 标签令人讨厌，我也这么认为。

格式

• 短文件比长文件更易于理解。确实是这样，一个文件行数太多，方法太多，跳转来跳转去的都麻烦。
• 关系密切的函数放在一起，只能尽量，有时可能一个函数和多个函数有关系，那应该把它们放一起了，结果其中一个函数又和另外的有关系，所以看另外一个函数的逻辑时，又得跨越多于一屏的去看
• “源文件最顶部应该给出高层次概念和算法。细节应该往下渐次展开，直至找到源文件中最底层的函数和细节。”
• 全局变量的声明都放到顶部去。大部分情况是如此，只是有时开发过程中，加一个变量，会懒得滑到文件顶部，直接在当前位置声明了变量，这个还是要改正。
• 代码行字符不要太多，要短小，千万不要到需要横向拖动才能看全的地步。
• 字符与符号间的空格，缩进，换行之类，已经属于常识了。