命名

大到项目名、模块名、包名、对外暴露的接口，小到类名、函数名、变量名、参数名，只要是做开发，我们就逃不过“起名字”这一关。

命名多长最合适？

• 在足够表达其含义的情况下，命名当然是越短越好。
• 对于一些默认的、大家都比较熟知的词，推荐用缩写，这样一方面能让命名短一些，另一方面又不影响阅读理解。
  • 比如，sec 表示 second、str 表示 string、num 表示 number、doc 表示 document。
• 对于作用域比较小的变量，我们可以使用相对短的命名，比如一些函数内的临时变量。
• 对于类名这种作用域比较大的，更推荐用长的命名方式。
• 命名的时候，我们一定要学会换位思考，假设自己不熟悉这块代码，从代码阅读者的角度去考量命名是否足够直观。

利用上下文简化命名

• 在 User 类这样一个上下文中，我们没有在成员变量的命名中重复添加“user”这样一个前缀单词，而是直接命名为 name、password、avatarUrl。
• 在使用这些属性时候，我们能借助对象这样一个上下文，表意也足够明确。
• 除了类之外，函数参数也可以借助函数这个上下文来简化命名。

命名要可读、可搜索

• 所说的“可读”，指的是不要用一些特别生僻、难发音的英文单词来命名。
• 我们在命名的时候，最好能符合整个项目的命名习惯。
  • 大家都用“selectXXX”表示查询，你就不要用“queryXXX”；
  • 大家都用“insertXXX”表示插入一条数据，你就要不用“addXXX”

如何命名接口和抽象类？

• 对于接口
  • 一种是加前缀“I”，表示一个 Interface。比如 IUserService，对应的实现类命名为 UserService。
  • 另一种是不加前缀，比如 UserService，对应的实现类加后缀“Impl”，比如 UserServiceImpl。
• 对于抽象类
  • 一种是带上前缀“Abstract”，比如 AbstractConfiguration；
  • 另一种是不带前缀“Abstract”。

注释

注释到底该写什么？

• 注释的内容一般包含三部分：做什么、为什么、怎么做。对于一些复杂的类和接口，我们可能还需要写明“如何用”。
• 函数和变量如果命名得好，确实可以不用再多写注释，但对于类来说，包含的信息就比较多，一个简单的命名就不能够全面详尽，这时候需要注释写做什么就合情合理了。
• 关于具体的代码实现思路，我们可以写一些总结性的说明、特殊情况的说明，让阅读的人不用看代码大致知道实现思路。
• 对于逻辑复杂不好提炼较短名称的函数，可以借助总结性的注释来让代码更清晰、更有条理。

注释是不是越多越好？

• 类和函数一定要写注释，而且要写得尽可能全面、详细，而函数内部的注释相对少一些，一般都是靠好的命名、提炼函数、解释性变量、总结性注释来提高代码的可读性。