《设计模式之美》理论五：让你最快速地改善代码质量的20条编程规范（上）

王争《设计模式之美》学习笔记

命名

命名多长最合适？

• 长的命名可以包含更多的信息，更能准确直观地表达意图，但最好不要长到两行的程度，影响代码的可读性。
• 在足够表达其含义的情况下，命名当然是越短越好。对于一些默认的、大家都比较熟知的词，我比较推荐用缩写。
• 对于作用域比较小的变量，我们可以使用相对短的命名，比如一些函数内的临时变量。
• 对于类名这种作用域比较大的，我更推荐用长的命名方式。

利用上下文简化命名

• 文中举例，在 User 类这样一个上下文中，我们没有在成员变量的命名中重复添加“user”这样一个前缀单词，而是直接命名为 name、password、avatarUrl。比如：user.getName()。这个问题还挺常见的。
• 函数参数也可以借助函数这个上下文来简化命名。

命名要可读、可搜索

• 我这里所说的“可读”，指的是不要用一些特别生僻、难发音的英文单词赖命名。
• 我们在 IDE 中编写代码的时候，经常会用“关键词联想”的方法来自动补全和搜索。我们在命名的时候，最好能符合整个项目的命名习惯。大家都用“selectXXX”表示查询，你就不要用“queryXXX”。这点也挺好挺有用的。

如何命名接口和抽象类

• 对于接口的命名，一般有两种比较常见的方式：
  • 一种是加前缀“I”，表示一个 Interface。比如 IUserService，对应的实现类命名为 UserService。
  • 另一种是不加前缀，比如 UserService，对应的实现类加后缀“Impl”，比如 UserServiceImpl。
• 对于抽象类的命名，也有两种方式：
  • 一种是带上前缀“Abstract”，比如 AbstractConfiguration。
  • 另一种是不带前缀“Abstract”。
• 对于接口和抽象类，选择哪种命名方式都是可以的，只要项目里能够统一就行。

注释

• 命名很重要，注释跟命名同等重要。
• 很多人说，好的命名完全可以替代注释。如果需要注释，那说明命名不够好，需要在命名上下功夫，而不是添加注释。
• 作者认为，这样的观点有点太过极端。命名再好，毕竟有长度限制，不可能足够详尽，而这个时候，注释就是一个很好的补充。
• 简直完全同意，项目通篇不写一个字注释的，不是装逼就是懒。

注释到底该写什么？

• 注释的目的就是让代码更容易看懂。
• 注释的内容主要包含这样三个方面：做什么、为什么、怎么做。
• 有些人认为，“做什么、怎么做”在代码中都可以体现出来，只需要写清楚“为什么”，表明代码的设计意图即可。我个人不是特别认可这样的观点：
  • 注释比代码承载的信息更多。对于类来说，包含的信息比较多，一个简单的命名就不够全面详尽了。这个时候，在注释中写明“做什么”就合情合理了。
  • 注释起到总结性作用、文档的作用。在注释中，关于具体的代码实现思路，我们可以写一些总结性的说明、特殊情况的说明。这样能够让阅读代码的人通过注释就能大概了解代码的实现思路，阅读起来就会更加容易。我们可能还需要在注释中写清楚“如何用”，举一些简单的 quick start 的例子，让使用者在不阅读代码的情况下，快速地知道该如何使用。
  • 一些总结性注释能让代码结构更清晰。对于逻辑比较复杂的代码或者比较长的函数，如果不好提炼、不好拆分成小的函数调用，那我们可以借助总结性的注释来让代码结构更清晰、更有条理。

注释是不是越多越好？

• 注释太多和太少都有问题。太多，有可能意味着代码写得不够可读，需要写很多注释来补充。
• 注释太多也会对代码本身的阅读起到干扰。而且，后期的维护成本也比较高，有时候代码改了，注释忘了同步修改，就会让代码阅读者更加迷惑。
• 类和函数一定要写注释，而且要写得尽可能全面、详细，而函数内部的注释要相对少一些，一般都是靠好的命名、提炼函数、解释性变量、总结性注释来提高代码的可读性。