《代码整洁之道》和《编写可维护代码的艺术》的总结与整合

最近读了《代码整洁之道》和《编写可维护代码的艺术》，发现两本书的核心思想非常一致，主要围绕以下几点：命名、注释、逻辑、函数、类、格式和组织。下面将这些内容整合记录，方便日后参考。

1. 命名

好的命名能够显著提升代码的可读性和可维护性，具有以下特征：

名副其实：名字应当清晰地表达变量、函数或类的用途。
名字与抽象层级符合：低层次逻辑用具体的名字，高层次逻辑用抽象的名字。
有表现力：名字能够传达代码的意图。
名字带上更多信息：如 userList 比 list 更有信息量。
大作用域的名字更长：全局变量和核心组件使用更长、更清晰的名字。
避免误导：避免使用类似或容易混淆的名字。
名字的区分有意义：例如 count 和 total 应该表达不同的含义。
可读、容易搜索：名字尽量简洁、直观，避免拼音或缩写。
统一命名：相同概念用相同的名字，例如统一使用 fetchData 而非 getData 和 loadData 混用。
少用双关语：减少歧义，确保代码语义清晰。
添加有意义的语境：通过前缀、后缀或命名空间提供额外信息，例如 user.getProfile() 而不是 get()。

2. 注释

注释的作用是补充代码的语义，而不是重复代码本身。以下是注释的原则：

注释的作用

记录想法和对代码的理解：帮助后续开发者理解设计思路。
提供信息：如时间复杂度、性能注意事项。
解释意图：记录代码的目的，而非实现细节。
警示和提醒：标记潜在的陷阱或风险。
TODO 注释：标记需要后续完成的任务。
说明常量的用途：如解释魔法数字的含义。
解答读者的疑问：例如为何使用某种特殊的实现。

好的注释特点

紧凑：简洁明了。
精准：直接表达意图。
用输入输出说明代码：注释说明代码如何作用于输入并产生输出。

3. 逻辑

逻辑代码的核心是简洁且易读，以下是优化逻辑的方式： • 让控制流更易读：例如 length < 10 好于 10 > length。 • 优先处理简单或可疑情况：使逻辑流程更直观。 • 使用卫语句提前结束逻辑：避免深层嵌套。 • 最小化嵌套：深层嵌套会增加阅读难度。 • 拆分超长表达式：复杂逻辑可以拆分成多个部分。 • 使用解释变量：用有意义的变量名代替复杂表达式。 • 总结变量代替一段代码：将结果存入变量以提高可读性。 • 减少不必要的变量：删除没有价值的中间变量。

4.函数

编写函数的核心原则是短小、专一、清晰： • 短小：尽量控制函数长度，避免超出可快速阅读的范围。 • 只做一件事：单一职责，避免一个函数承担多种功能。 • 不重复：减少重复逻辑，避免冗余。 • 单一抽象层级：函数内部只处理同一抽象层次的逻辑。 • 避免多参数：尽量减少参数数量，必要时将参数封装成对象。 • 分割查询函数和指令函数：避免混合数据获取和副作用。

5. 类

面向对象代码中的类需要满足以下条件： • 短小：每个类的代码尽量保持简洁。 • 单一权责：一个类只负责一类功能。 • 内聚：相关的功能集中在一个类中。 • 易于修改：类的设计应方便扩展和修改。

6. 格式

一致的代码格式可以提升代码的可读性： • 一致的布局：例如缩进风格、括号位置等保持统一。 • 相关代码分组：形成逻辑清晰的代码块。 • 列对齐：适当时可以对齐代码列以增强直观性。 • 有意义的排序：例如根据逻辑顺序或重要性排序函数和变量。 • 分段代码：通过空行分隔逻辑段落。 • 自上而下的可读性：让代码可以从上往下顺序阅读。 • 意思相近的代码靠近：将相关逻辑放在一起，避免逻辑分散。

组织

良好的代码组织是可维护性的基础： • 抽取子问题：将复杂问题拆分成多个简单问题。 • 工具代码统一维护：通用代码模块化。 • 简化接口：避免复杂的调用逻辑。 • 按需重塑接口：为不同的需求提供简洁的接口。 • 使用自然语言描述代码：让代码接近业务语义。 • 少写代码：代码越少，出错的机会越少。 • 使用参数控制顺序逻辑：避免硬编码顺序。