docs(software-engineering): 更新整洁代码文档内容

更新了整洁代码相关文档，主要包括：
- 移除标题中的加粗标记，使格式更加简洁统一
- 修改核心概念部分，将表格形式改为树状结构展示四大维度
- 调整命名准则中业务性与技术性的优先级表述
- 优化错误处理和边界管理等内容的描述
- 更新关联内容链接，替换为更相关的技术债务主题
- 修正部分措辞和表达，提升文档可读性

Author: 0xcaffebabe

doc/软件工程/软件设计/代码质量/整洁代码.md

@@ -4,7 +4,7 @@ tags: ['软件工程', '设计模式']
 
 # 整洁代码
 
-## **概述（Overview）**
+## 概述
 
 整洁代码是一套使软件系统更易读、易维护、可演化的工程实践体系。
 其核心目的是：**让代码成为开发者之间精确、可持续的沟通媒介**。
@@ -18,18 +18,16 @@ tags: ['软件工程', '设计模式']
 * **表达力（Expressiveness）**
 * **软件设计原则的落地（SRP / OCP / DIP / LSP 等）**
 
-整洁代码不是“写漂亮代码”，而是“写让系统长期健康发展的代码”。
+这六项都服务于同一个目标——降低软件系统的长期总成本。可读性/表达力降低沟通成本，低复杂度/可维护性降低变更成本，可演化性/SOLID 落地降低架构腐化成本。
 
----
-
-## **本质（Essence）**
+## 本质
 
 整洁代码的本质可以归纳为四个核心思想：
 
 1. **代码是需求的最精确表达**
    软件需求最终都要落实为源代码，代码质量决定了系统的真实状态。
 
-2. **代码主要是“写给人读的”**
+2. **代码主要是"写给人读的"**
    系统生命周期中，读代码的时间远大于写代码。
 
 3. **整洁性源于高质量的抽象与边界设计**
@@ -55,40 +53,41 @@ tags: ['软件工程', '设计模式']
 
 ```
 
----
-
-## **核心概念（Core Concepts）**
+## 核心要素
 
 整洁代码可以抽象为四大维度：
 
-| 维度  | 本质    |
-| --- | ----- |
-| 表达力 | 让意图清晰 |
-| 结构性 | 让职责清晰 |
-| 边界性 | 让耦合可控 |
-| 演化性 | 让变更安全 |
+```
+整洁代码
+├── 表达力（Naming, Functions, Comments, Formatting）
+│   └── 准则：意图清晰、无歧义、可搜索
+├── 结构性（Classes, Object/Data, Error Handling）
+│   └── 准则：职责单一、内聚性高、封装完整
+├── 边界性（Boundaries, Third-party Isolation）
+│   └── 准则：依赖最少、接口稳定、隔离良好
+└── 演化性（Iteration, Concurrency, System Design）
+    └── 准则：变更成本低、可测试、风险可控
+```
 
 好命名产生好函数
-
 好函数组成好类
-
 好类构建好模块
-
 好模块形成清晰边界
-
 清晰边界支撑健康架构
 
-### 1. **命名（Naming）**
+### 命名
 
 命名是抽象与表达力的第一层。好命名具备：
 
 * **名副其实**（表达其作用）
 * **避免误导**
 * **具备可搜索性**
 * **上下文一致性**
-* **技术性优于业务性（有明确语义时）**
+* **业务性优于技术性（有明确语义时）**
 
-### 2. **函数（Functions）**
+命名是意义的载体。好命名把意义从隐式（藏在实现里）变为显式（直接体现在命名中），从而降低整个系统的认知成本
+
+### 函数
 
 整洁函数的三个特征：
 
@@ -105,9 +104,11 @@ tags: ['软件工程', '设计模式']
 * 使用异常而非错误码
 * 指令与询问分离（Command-Query Separation）
 
-### 3. **注释（Comments）**
+所有这些要求服务于同一个核心——让代码**可推导、可验证、可复用**。复杂是必然的，但这些约束把复杂从"无序的分散在各处"变成"有序的局部化"。
+
+### 注释
 
-注释是“失败的设计所需的补丁”。
+注释是"失败的设计所需的补丁"。
 只有在以下情况必须存在：
 
 * 法律信息
@@ -123,27 +124,19 @@ tags: ['软件工程', '设计模式']
 * 记录式注释
 * 注释掉的代码
 
-### 4. **格式（Formatting）**
+注释存在的唯一理由是**补充代码无法表达的信息**——决策理由、隐式依赖、契约声明。其余一切注释都是噪声，甚至是误导源。
+
+### 格式
 
 格式体现结构与表达能力：
 
 * 垂直格式：相近概念靠近、空行作为语义切分
 * 横向格式：短行、合理空格
 * 缩进表达结构范围
 
-### 5. **对象与数据结构（Objects & Data Structures）**
+良好格式的本质是：消除语义结构与视觉呈现之间的信息损耗。
 
-体现了面向对象与过程式的基本差异：
-
-* OO：易添加类型（行为）
-* 数据结构：易添加函数（操作）
-
-并遵循：
-
-* 迪米特法则（Law of Demeter）
-* DTO 保持纯数据，不放逻辑
-
-### 6. **错误处理（Error Handling）**
+### 错误处理
 
 整洁的错误处理：
 
@@ -153,15 +146,15 @@ tags: ['软件工程', '设计模式']
 * 使用特例模式（Null Object Pattern）
 * 不传递 null
 
-### 7. **边界（Boundaries）**
+### 边界
 
 边界是整洁架构的关键：
 
 * 封装第三方库
 * 通过适配器隔离未实现或变化中的接口
 * 使用学习性测试保护升级
 
-### 8. **类（Classes）**
+### 类
 
 类应：
 
@@ -171,13 +164,13 @@ tags: ['软件工程', '设计模式']
 * 有清晰的职责拆分（SRP）
 * 使用接口隔离
 
-### 9. **系统架构级整洁性（System-Level Cleanliness）**
+### 系统架构级整洁性
 
 * 构造与使用分离
 * 使用 DI、Factory、Main 组件
 * 可测试架构（TDD-friendly）
 
-### 10. **迭进设计（Evolutionary Design）**
+### 迭进设计
 
 四个约束：
 
@@ -186,53 +179,39 @@ tags: ['软件工程', '设计模式']
 * 表达力高
 * 尽可能减少类和方法数量
 
-### 11. **并发编程（Concurrency）**
+### 并发编程
 
 并发是解耦时间与逻辑的手段，但需遵循：
 
 * 封装共享数据
 * 使用数据副本降低冲突
 * 精简同步范围
 * 识别经典模型（生产者消费者/读写者/哲学家就餐）
-* 通过“欺骗性失败”测试验证线程安全
-
----
+* 通过"欺骗性失败"测试验证线程安全
 
-## **分类体系（Taxonomy）**
+## 应用场景
 
-整洁代码元素可按照“表达力—结构性—边界性—演化性”划分：
-
-```
-整洁代码
-├── 表达力（Naming, Functions, Comments, Formatting）
-├── 结构性（Classes, Object/Data, Error Handling）
-├── 边界性（Boundaries, Third-party Isolation）
-└── 演化性（Iteration, Concurrency, System Design）
-```
-
----
-
-## **应用场景（Use Cases / Applications）**
-
-### ✔ 适用于所有软件开发场景，尤其是：
+### 适用于所有软件开发场景，尤其是：
 
 * 快速迭代型系统
 * 需要长期维护的大型系统
 * 高人员流动率的团队
 * 多人协作的复杂项目
 * 对稳定性和可扩展性要求高的系统（金融、电商、基础设施）
 
-### ✔ 特别重要的领域：
+根本原因：整洁代码解决的是长期维护、多人协作、持续演化场景下的沟通成本与变更成本问题。越是这类场景，收益越大
+
+### 特别重要的领域：
 
 * 架构设计
 * 领域建模
 * 核心业务逻辑
 * SDK / API 设计
 * 并发与异步系统
 
----
+这五类场景都是高不确定性、高变更频率、高协作成本的区域。整洁代码在简单场景下收益有限（问题本身不严重），但在这类复杂场景下，收益将被放大
 
-## **关联关系（Relations / Dependencies）**
+## 关联关系
 
 整洁代码与其他工程实践的关系：
 
@@ -242,62 +221,49 @@ tags: ['软件工程', '设计模式']
 | **重构（Refactoring）**        | 重构是整洁代码的落地方式                         |
 | **设计模式**                   | 模式提供结构，整洁代码提供表达力与可维护性                |
 | **SOLID 原则**               | 整洁代码是 SOLID 的工程实践表现                  |
-| **架构（Clean Architecture）** | 整洁建筑在整洁代码原则上                         |
+| **架构（Clean Architecture）** | 整洁架构在整洁代码原则上                         |
 | **领域驱动设计（DDD）**            | 清晰命名、明确边界是 DDD 的基础                   |
 
----
-
-## **发展趋势（Evolution / Trends）**
+## 发展趋势
 
 未来整洁代码的发展方向：
 
-### 1. **语言与工具推动“自动整洁”**
+### 语言与工具推动"自动整洁"
 
 * 静态分析器（Sonar、Checkstyle）
 * LLM 自动重构
 * 自动命名建议
 * 自动边界封装
 
-### 2. **架构整洁度要求提升**
+### 架构整洁度要求提升
 
 随着微服务、Serverless、云原生普及，边界隔离更重要。
 
-### 3. **测试驱动架构（TDA）深化**
+### 测试驱动架构（TDA）深化
 
 可测试架构不再是可选项。
 
-### 4. **开发者体验（DX）驱动的整洁代码标准化**
+### 开发者体验（DX）驱动的整洁代码标准化
 
 团队协作要求统一风格与结构。
 
-### 5. **LLM 辅助“表达力增强”**
-
-模型能提供最佳命名、重构方案，有助降低认知负担。
-
----
-
-## **总结（Conclusion）**
-
-整洁代码是一套贯穿整个软件生命周期的工程思想。
-其目标不是"写出优美代码"，而是**让系统长期保持可持续演化能力**。
-
-整洁代码体系可归纳为：
-
-* **表达力**：命名、函数、注释、格式
-* **结构性**：类、对象/数据、错误处理
-* **边界性**：第三方隔离、适配器、可测试性
-* **演化性**：并发、架构、迭进设计、重构
+### LLM 辅助"表达力增强"
 
-最终目标是构建：
+模型能提供最佳命名、重构方案，但同时存在副作用：
 
-> **简单、清晰、稳定、可拓展的系统——真正能伴随业务长期发展的软件。**
+* **幻觉与置信度危机**：AI给出的命名和重构方案可能看似合理实则错误，高置信度不等于高质量
+* **上下文缺失**：无法理解团队代码风格与架构约定，生成的命名可能与系统风格割裂
+* **架构判断缺失**：按教科书模式生成代码，不适配当前系统上下文
+* **风格不一致**：生成代码不符合团队标准，增加认知负担
+* **Vibe Coding门槛降低**：代码生成容易，但长期可读性和可维护性风险上升
 
-## 关联内容（自动生成）
+## 关联内容
 
 - [/软件工程/软件设计/代码质量/代码重构.md](/软件工程/软件设计/代码质量/代码重构.md) 整洁代码与重构密切相关，重构是实现和维护整洁代码的重要手段
 - [/软件工程/软件设计/代码质量/代码质量.md](/软件工程/软件设计/代码质量/代码质量.md) 代码质量是整洁代码的宏观概念，整洁代码是提升代码质量的具体实践方法
 - [/软件工程/软件设计/代码质量/编码规范.md](/软件工程/软件设计/代码质量/编码规范.md) 编码规范是整洁代码的基础要求，两者都旨在提升代码可读性和可维护性
 - [/软件工程/软件设计/代码质量/代码审查.md](/软件工程/软件设计/代码质量/代码审查.md) 代码审查是确保整洁代码标准得到贯彻的重要实践环节
+- [/软件工程/软件设计/代码质量/软件测试/自动化测试.md](/软件工程/软件设计/代码质量/软件测试/自动化测试.md) 自动化测试是迭进设计和TDD的基础，保障重构安全性
 - [/软件工程/设计模式/设计模式.md](/软件工程/设计模式/设计模式.md) 设计模式与整洁代码相互促进，模式提供结构，整洁代码提升表达力和可维护性
 - [/软件工程/软件设计/软件设计.md](/软件工程/软件设计/软件设计.md) 软件设计原则指导整洁代码的实现，是整洁代码的理论基础
 - [/软件工程/软件设计/代码质量/软件测试/单元测试.md](/软件工程/软件设计/代码质量/软件测试/单元测试.md) 单元测试与TDD是整洁代码的基石，保证代码的可测试性和重构的安全性
@@ -306,6 +272,6 @@ tags: ['软件工程', '设计模式']
 - [/软件工程/理论/敏捷软件开发.md](/软件工程/理论/敏捷软件开发.md) 整洁代码是敏捷开发中的重要实践，支持快速迭代和持续交付
 - [/软件工程/架构/架构治理.md](/软件工程/架构/架构治理.md) 架构治理中包含代码整洁性的要求和规范
 - [/软件工程/架构/架构重构.md](/软件工程/架构/架构重构.md) 架构重构是整洁代码理念在系统层面的扩展
-- [/数据技术/数据治理.md](/数据技术/数据治理.md) 数据治理中的命名规范与代码整洁性中的命名原则有相似之处
+- [/软件工程/架构/技术债务.md](/软件工程/架构/技术债务.md) 整洁代码是预防和控制技术债务的核心手段
 - [/编程语言/编程范式/面向对象.md](/编程语言/编程范式/面向对象.md) 面向对象编程原则（如SOLID）是整洁代码的重要理论基础
 - [/编程语言/并发模型.md](/编程语言/并发模型.md) 并发代码的整洁性有特殊要求，需要特别注意错误处理和可读性