可维护性

副标题 / 摘要 注释不是越多越好，而是要写“为什么”和“约束”。本文给出注释的使用原则与实践建议。 目标读者 需要维护多人协作代码库的工程师 负责代码评审的开发者 想提升可读性的团队 背景 / 动机 很多注释只是复述代码本身，反而会过时并误导。 好的注释应该解释“意图、约束和风险”。 核心概念 注释的价值：解释意图与约束 注释的风险：过时、与代码不一致 自解释代码：清晰命名与结构 实践指南 / 步骤 优先让代码自解释 用注释说明“为什么” 记录边界条件与陷阱 避免重复代码语义 注释必须随代码更新 可运行示例 # 好注释：说明为什么要这么做 def get_user(user_id, cache): # 避免热 key 反复击穿数据库 if user_id in cache: return cache[user_id] return None 解释与原理 注释的核心价值是“传递上下文”。 代码告诉你“做了什么”，注释告诉你“为什么这样做”。 常见问题与注意事项 注释越少越好吗？ 不一定，关键是信息密度。 什么时候必须写注释？ 边界条件、性能技巧、安全逻辑。 TODO 注释合理吗？ 可以，但必须有可追踪的任务编号。 最佳实践与建议 写“意图”和“约束” 避免“翻译式注释” 注释更新纳入评审 小结 / 结论 注释是沟通工具，不是装饰。 写对注释能显著降低维护成本。 参考与延伸阅读 Clean Code The Pragmatic Programmer 元信息 阅读时长：6~8 分钟 标签：注释、代码规范、可维护性 SEO 关键词：代码注释, 可维护性 元描述：注释什么时候有用，以及如何正确编写。 行动号召（CTA） 在一次代码评审中标注“为什么”的注释，而不是“做了什么”。

副标题 / 摘要 内聚关注“模块内部是否紧密相关”，耦合关注“模块之间是否依赖过多”。本文给出区别与改进方法。 目标读者 需要评估设计质量的工程师 负责重构与模块划分的开发者 做架构与代码评审的团队 背景 / 动机 很多系统难维护的原因不是“功能太多”，而是模块内聚低、耦合高。 理解内聚与耦合，是设计优化的基础。 核心概念 内聚（Cohesion）：模块内部的相关性 耦合（Coupling）：模块之间的依赖程度 高内聚、低耦合：可维护性最佳 实践指南 / 步骤 识别“职责过多”的模块 拆分低内聚模块 减少跨模块直接依赖 用接口隔离依赖 引入依赖注入 可运行示例 # 低内聚示例：一个类做太多事 class OrderManager: def calculate(self): pass def save(self): pass def send_email(self): pass # 改进：拆分职责 class OrderCalculator: def calculate(self): pass class OrderRepository: def save(self): pass class OrderNotifier: def send_email(self): pass 解释与原理 内聚高意味着模块职责单一、变化集中； 耦合低意味着模块之间依赖少、替换成本低。 常见问题与注意事项 模块越小内聚就越高吗？ 不一定，小但职责混杂仍然低内聚。 完全无耦合可能吗？ 不可能，关键是控制依赖方向与数量。 怎么衡量？ 看模块修改是否牵连多处。 最佳实践与建议 一个模块只解决一个问题 把依赖集中到边界层 用接口隔离变化 小结 / 结论 内聚与耦合是判断设计质量的核心指标。 高内聚、低耦合是长期可维护系统的基础。 ...

副标题 / 摘要 TDD 的核心不是“测试优先”，而是“反馈优先”。本文解释为何先写测试能改善设计与质量。 目标读者 想尝试 TDD 的开发者 需要提升测试覆盖与设计质量的团队 负责工程规范的技术负责人 背景 / 动机 不写测试容易导致“改一点坏一片”。 TDD 通过先写测试迫使开发者明确需求与接口，从而降低返工成本。 核心概念 红-绿-重构：测试失败 -> 通过 -> 改进结构 最小实现：写刚好够通过测试的代码 反馈循环：快速验证假设 实践指南 / 步骤 先写失败的测试（定义行为） 写最小实现通过测试 重构代码保持测试通过 重复循环 可运行示例 # 测试 def test_sum(): assert add(1, 2) == 3 # 实现 def add(a, b): return a + b if __name__ == "__main__": test_sum() print("ok") 解释与原理 先写测试意味着先定义“期望行为”，再实现。 这会让接口更清晰、设计更简洁。 常见问题与注意事项 TDD 会不会降低效率？ 初期可能慢，但长期返工成本更低。 所有场景都适合 TDD 吗？ 不一定，探索性研发可先实验后补测试。 TDD 会导致过度设计吗？ 如果坚持“最小实现”，反而能控制复杂度。 最佳实践与建议 从核心逻辑开始做 TDD 保持测试小而快 把重构纳入流程 小结 / 结论 TDD 的价值是清晰需求、快速反馈与稳定演进。 先写测试不是教条，而是降低风险的方式。 ...

副标题 / 摘要 重构不是“重写”，而是持续改善代码结构。本文给出重构适用场景、触发信号与控制风险的方法。 目标读者 需要维护遗留系统的工程师 负责技术债管理的团队 关注代码质量的开发者 背景 / 动机 不重构，技术债会持续累积；盲目重构，又可能影响交付。 理解“何时重构”比“怎么重构”更重要。 核心概念 技术债：当前效率换取未来成本 重构：不改变外部行为的结构改进 触发信号：重复代码、复杂度上升、修改成本高 实践指南 / 步骤 识别高频修改区域 先补齐测试 小步重构，持续验证 避免大规模“重写” 把重构与业务迭代结合 可运行示例 # 重构前 def calc_total(items): total = 0 for name, price in items: if price > 0: total += price return total # 重构后 def calc_total(items): return sum(price for _, price in items if price > 0) 解释与原理 重构的价值在于降低未来修改成本。 如果一个模块频繁修改且修改困难，就应该优先重构。 常见问题与注意事项 重构是不是浪费时间？ 如果能降低长期成本，就不是浪费。 什么时候不该重构？ 即将下线的模块不值得投入。 如何控制风险？ 小步重构 + 测试覆盖。 最佳实践与建议 把重构纳入日常开发 优先处理“高频痛点”模块 用指标评估重构收益 小结 / 结论 重构适合在“高频修改、高复杂度”的模块中进行。 控制风险的关键是测试与小步迭代。 ...

副标题 / 摘要 迪米特法则强调“只和直接朋友说话”。本文用示例说明违规写法，并给出修复方式。 目标读者 想降低耦合的工程师 负责代码评审与重构的开发者 需要维护大型系统的团队 背景 / 动机 深层链式调用让对象之间依赖过强，改动一个结构就影响一大片。 迪米特法则就是用来控制这种耦合的。 核心概念 最少知识原则：对象只了解直接依赖 消息委托：把内部结构封装在对象内 耦合控制：减少“链式访问” 实践指南 / 步骤 识别链式调用（a.b.c.d） 让中间对象提供必要方法 封装内部结构 避免跨层访问内部字段 可运行示例 class Wallet: def __init__(self, balance): self.balance = balance def has_enough(self, amount): return self.balance >= amount class User: def __init__(self, wallet): self.wallet = wallet def can_pay(self, amount): return self.wallet.has_enough(amount) def checkout(user, amount): # 违例：user.wallet.balance # 修复：user.can_pay return user.can_pay(amount) 解释与原理 通过让 User 暴露 can_pay 方法，调用方无需知道 wallet 的内部结构。 这样 wallet 内部变化时，调用方不需要改动。 ...

副标题 / 摘要 空对象模式用“可用但无效果”的对象替代 null，减少分支判断与空指针风险。本文给出适用场景与示例。 目标读者 频繁处理空指针的工程师 需要简化分支逻辑的开发者 关注代码可读性的团队 背景 / 动机 到处写 if obj is None 会让代码变得难读且易遗漏。 空对象模式通过提供“默认实现”，让调用方无需关心空值。 核心概念 空对象：实现相同接口但执行空操作 统一接口：调用方不区分真实对象与空对象 可替代性：替代 null 而不破坏逻辑 实践指南 / 步骤 定义统一接口 实现真实对象与空对象 在创建阶段选择真实/空对象 调用方不写 null 分支 可运行示例 class Notifier: def send(self, msg: str) -> None: raise NotImplementedError class EmailNotifier(Notifier): def send(self, msg: str) -> None: print("email:", msg) class NullNotifier(Notifier): def send(self, msg: str) -> None: pass def get_notifier(enabled: bool) -> Notifier: return EmailNotifier() if enabled else NullNotifier() if __name__ == "__main__": notifier = get_notifier(False) notifier.send("hello") # 不需要 if 判断 解释与原理 空对象模式把“缺失”变成一个合法对象。 这样调用方无需分支判断，避免空指针错误。 ...

副标题 / 摘要 继承容易让系统变脆，组合让系统更灵活。本文解释为什么组合更适合工程演进，并给出实用示例。 目标读者 写面向对象代码的工程师 负责模块演进与重构的开发者 做代码评审与架构设计的团队 背景 / 动机 继承会把父类的实现细节暴露给子类，容易导致“脆弱基类问题”。 组合通过“把能力作为对象注入”来降低耦合，更易测试与替换。 核心概念 继承（Inheritance）：is-a 关系，强耦合 组合（Composition）：has-a 关系，弱耦合 脆弱基类问题：父类改动导致子类行为改变 实践指南 / 步骤 优先建接口，延后继承 把可变行为抽成组件 用组合注入行为 通过依赖替换实现测试 只在“稳定共性”时使用继承 可运行示例 class Logger: def log(self, msg: str) -> None: print(msg) class FileSaver: def save(self, data: str) -> None: print("save", data) class ReportService: def __init__(self, logger: Logger, saver: FileSaver): self.logger = logger self.saver = saver def run(self, data: str) -> None: self.logger.log("start") self.saver.save(data) self.logger.log("done") if __name__ == "__main__": svc = ReportService(Logger(), FileSaver()) svc.run("report") 解释与原理 组合让行为可替换（如 Logger 可以换成 Mock）。 继承则把依赖固定在父类上，一旦父类变化，子类难以控制影响。 ...

副标题 / 摘要 好代码不是“聪明”，而是“可理解、可验证、可演进”。本文给出工程视角的判断标准与实践方法。 目标读者 想提升代码质量的工程师 负责代码评审的团队 需要建立编码规范的技术负责人 背景 / 动机 代码质量决定维护成本与交付速度。 在多人协作中，好代码比“聪明代码”更重要。 核心概念 可读性：降低理解成本 可测试性：能被自动验证 可演进性：便于修改与扩展 实践指南 / 步骤 写清晰命名与结构 保持函数短小、职责单一 用测试锁定核心逻辑 减少隐式依赖与副作用 可运行示例 # 不好：命名与职责不清晰 def f(x): if x > 0: return x * 1.08 return x # 更好：意图清晰 def apply_tax(price): if price <= 0: return price return price * 1.08 if __name__ == "__main__": print(apply_tax(100)) 解释与原理 好代码的价值不在于“技巧”，而在于团队可以快速理解与修改。 可读性、可测试性与可演进性是关键指标。 常见问题与注意事项 短代码一定更好吗？ 不一定，重要的是表达清晰。 注释能替代可读性吗？ 不能，注释应补充而不是替代。 可测试性为什么重要？ 它是安全改动的基础。 最佳实践与建议 代码评审关注意图表达 建立清晰的命名规范 把复杂逻辑拆成小函数 小结 / 结论 好代码让团队更快、更稳地交付。 可读、可测、可演进是长期价值的核心。 ...

副标题 / 摘要 三层架构通过分离展示、业务与数据层，降低耦合与维护成本。本文讲清职责边界与工程价值。 目标读者 负责系统设计与分层的工程师 需要规范代码结构的团队 想降低耦合与提升维护性的开发者 背景 / 动机 业务系统复杂度上升时，代码容易变成“泥球”。 三层架构提供了一种稳定的分层结构，帮助控制复杂性。 核心概念 表现层（Presentation）：UI / API 接口 业务层（Business）：核心业务规则 数据层（Data）：数据库与外部存储 实践指南 / 步骤 定义清晰的层边界 禁止跨层直连（表现层不直接访问数据库） 业务层成为唯一的规则入口 数据层只负责持久化 用接口隔离依赖 可运行示例 class UserRepository: def get(self, user_id): return {"id": user_id, "name": "Alice"} class UserService: def __init__(self, repo): self.repo = repo def profile(self, user_id): user = self.repo.get(user_id) return {"id": user["id"], "display": user["name"].upper()} class UserAPI: def __init__(self, service): self.service = service def handle(self, user_id): return self.service.profile(user_id) 解释与原理 三层架构的核心是“职责分离”。 各层只关心自己的问题，减少依赖与变更扩散。 常见问题与注意事项 三层会不会过度设计？ 对小项目可能是，但中大型系统很有价值。 ...

副标题 / 摘要 封装不是“把字段设为 private”，而是建立稳定边界，让变化被隔离。本文解释封装的工程价值与落地方法。 目标读者 写业务系统但经常“改一处坏一片”的工程师 希望提升模块边界设计的开发者 负责代码评审和架构演进的技术负责人 背景 / 动机 没有封装，系统就像没有隔间的办公室：任何一个变化都会影响到其他部分。 封装能让变化局部化、减少耦合、提高可读性与可测试性。 核心概念 信息隐藏：内部实现细节不暴露给外部 稳定边界：对外只暴露行为和契约 高内聚、低耦合：模块内紧密相关，模块间依赖最小 实践指南 / 步骤 先定义对外行为：先有接口，再有实现。 隐藏数据结构：不要让外部直接依赖内部表示。 用方法维护不变量：禁止外部绕过规则直接改数据。 把变化集中在模块内部：外部只看到稳定契约。 为封装加测试：通过行为测试保证边界稳定。 可运行示例 class BankAccount: def __init__(self, balance: int): self._balance = balance def deposit(self, amount: int) -> None: if amount <= 0: raise ValueError("amount must be positive") self._balance += amount def withdraw(self, amount: int) -> None: if amount <= 0: raise ValueError("amount must be positive") if amount > self._balance: raise ValueError("insufficient balance") self._balance -= amount def balance(self) -> int: return self._balance if __name__ == "__main__": acc = BankAccount(100) acc.deposit(50) acc.withdraw(30) print(acc.balance()) 解释与原理 封装的本质是 把“规则”放到模块内部。 外部只调用方法，不触碰内部状态，这样就能保证不变量始终成立。 当实现方式变化时，只要接口不变，外部代码无需调整。 ...