在计算机科学中有两件难事：缓存失效和命名。 --- Martin Fowler

命名

• 命名的过程本身就是一个抽象和思考的过程

变量名

• 能够正确地描述业务
• 代码的可搜索性

函数名

• 函数的命名要体现做什么

类名

• 实体类
  • 承载了核心业务数据和核心业务逻辑
  • 命名要充分体现业务语义，并在团队内达成共识
  • 例如：Customer、Bank和Employee等
• 辅助类
  • 辅佐实体类一起完成业务逻辑的
  • 其命名要能够通过后缀来体现功能
  • 例如：用来为Customer做控制路由的控制类CustomerController、提供Customer服务的服务类CustomerService、获取数据存储的仓储类CustomerRepository。
  • 辅助类，尽量不要用Helper、Util之类的后缀，因为其含义太过笼统，容易破坏SRP（单一职责原则）

包名

• 包代表了一组有关系的类的集合，起到分类组合和命名空间的作用
• 包的命名要适中，不能太抽象，也不能太具体。

模块名

• 模块（Module）主要是指Maven中的Module，相对于包来说，模块的粒度更大，通常一个模块中包含了多个包。

一致性

• 保持命名的一致性，可以提高代码的可读性，从而简化复杂度。因此，我们要小心选择命名，一旦选中，就要持续遵循，保证名称始终一致。
• 每个概念一个词

image.png

对仗词

• add/remove
• increment/decrement
• open/close
• begin/end
• insert/delete
• show/hide
• create/destroy
• lock/unlock
• source/target
• first/last
• min/max
• start/stop
• get/set
• next/previous
• up/down
• old/new

后置限定词

• 把限定词加到名字的最后，并在项目中贯彻执行，保持命名风格的一致性。
• 例如revenueTotal（总收入）、expenseTotal（总支出）、revenueAverage（平均收入）和expenseAverage（平均支出）。

统一业务语言

• 确保团队在内部的所有交流、模型、代码和文档中都要使用同一种编程语言

统一技术语言

• 有些技术语言是通用的，业内人士都能理解，我们应该尽量使用这些术语来进行命名，DO、DAO、DTO、ServiceI、ServiceImpl、Component和Repository等

设计模式语言

• 在技术人员之间共享和使用设计模式语言，可以极大地提升沟通的效率。

注释

• 如果注释是为了阐述代码背后的意图，那么这个注释是有用的

命名工具

• OnlineSearch 插件

规范

信息熵

• 信息熵是一条信息的信息量大小和它的不确定性之间的关系
• 事物的复杂程度在很大程度上取决于其有序程度，减少无序能在一定程度上降低复杂度，这正是规范的价值所在。
• 通过【规范】，无序的混沌控制在一个能够理解的范围内，从而帮助我们减少认知成本，降低对事物认知的复杂度。

认知成本

• 认知，指人们获得知识或应用知识的过程
• 知识，是人类对经验范围内的感觉进行总结归纳之后发现的规律。

混乱的代价

• 让我们对事物无法形成有效的记忆和认知，导致我们每次面对的问题都是
  新问题，每次面临的场景都是新场景，又要重新理解一遍。

代码规范

• 代码格式 ：包括缩进、水平对齐、注释格式等

空行规范

• 一个简单的原则就是将概念相关的代码放在一起：相关性越强，彼此之间的距离应该越短。

命名规范

• 面向对象和面向过程
• 强类型语言和弱类型语言
• Java：
  • 类名采用“大驼峰”形式，即首字母大写的驼峰，例如Object、StringBuffer、FileInputStream。
  • 方法名采用“小驼峰”形式，即首字母小写的驼峰，方法名一般为动词，与参数组成动宾结构，例如Thread的sleep(long millis)、StringBuffer的append(String str)。
  • 常量命名的字母全部大写，单词之间用下划线连接，例如TOTAL_COUNT、PAGE_SIZE等。
  • 枚举类以Enum或Type结尾，枚举类成员名称需要全大写，单词间用下划线连接，例如SexEnum.MALE、SexEnum.FEMALE。
  • 抽象类名使用Abstract开头；异常类使用Exception结尾；实现类以impl结尾；测试类以它要测试的类名开始，以Test结尾。
  • 包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词，包名统一使用单数形式。通常以com或org开头，加上公司名，再加上组件或者功能模块名，例如org.springframework.beans。

日志规范

• 日志输出级别：OFF、FATAL、ERROR、WARN、INFO、DEBUG、ALL或者自定义的级别。
• ERROR级别：表示不能自己恢复的错误，需要立即被关注和解决。
• WARN级别：对于可预知的业务问题，最好不要用ERROR输出日志，以免污染报警系统。使用WARN配置一个适当阈值的报警
• INFO级别：INFO用于记录系统的基本运行过程和运行状态。
• DEBUG级别：DEBUG是输出调试信息，如request/response的对象内容。在输出对象内容时，要覆盖Object的toString方法，否则输出的是对象的内存地址，就起不到调试的作用了。

异常规范

• 异常处理