在风电场监控系统的前两年，我写的文档只有两种：给领导看的PPT和给接锅人看的wiki页面。前者满是架构图和箭头，后者通常只有一句话——“部署文档见运维手册”。

而运维手册并不存在。

直到有一次，一个新来的同事花了一周时间才搞懂我写的报警模块配置流程。他跑来问我，我说”这个你看看代码就明白了”。他真的去看了。三天后他在Slack上说：”看懂了，但为什么不写个README？”

那个星期我在工位上坐了很久。一个工作了十年的架构师，交付的系统没有一份像样的文档。

代码自解释的三个层次

后来我慢慢总结出来，代码的”自解释”并非不写注释，核心在于分三个层次让代码自己说话。

第一层：命名

这一层很基础，但十年了还是看到有人写 List<String> list1 = new ArrayList<>()。

在风电数据采集模块里，我见过这样的代码：

1
2
3
4
5
6
7
8
9
// 改之前
public void process(List<Map<String, Object>> data) {
    for (Map<String, Object> d : data) {
        Object v = d.get("v");
        if (v != null && ((Number) v).doubleValue() > 25.0) {
            sendAlert(d);
        }
    }
}

25.0是什么？v是什么？sendAlert发给谁？不看上下文根本猜不出来。

改完后：

1
2
3
4
5
6
7
8
9
private static final double WIND_SPEED_ALERT_THRESHOLD = 25.0; // m/s

public void checkWindSpeedAlerts(List<TurbineReading> readings) {
    for (TurbineReading reading : readings) {
        if (reading.getWindSpeed() > WIND_SPEED_ALERT_THRESHOLD) {
            alertService.sendWindSpeedAlert(reading);
        }
    }
}

区别在于：读到第二段代码的人，不需要打开任何文档就知道——这是检查风速报警的，阈值25米/秒，超了就发报警。

命名原则很简单，但做到位需要刻意练习：

  • 变量名描述”是什么”，方法名描述”做什么”
  • 布尔变量用is/has/can前缀（isEnabled、hasAlarm）
  • 避免缩写，除非是领域通用术语（如IoTDB、SCADA）
  • 常量全大写，带业务含义（用WIND_SPEED_ALERT_THRESHOLD而非模糊的THRESHOLD）

第二层：结构

结构说的是代码的组织方式。一个方法多长算太长？我的标准是：如果不能在一屏内看完，就太长了。

但更实际的标准是：一个方法只做一件事。

风电场有个需求：根据风速、转速、温度三个维度判断风机是否健康。以前的代码把采集、计算、判断、报警全塞在一个方法里，大概300行。后来我拆成了四个方法：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
public class TurbineHealthMonitor {

    /**
     * 评估风机健康状态：采集数据 → 计算指标 → 判断状态 → 触发报警
     */
    public void evaluate(TurbineId turbineId) {
        TurbineSnapshot snapshot = collector.collect(turbineId);
        HealthMetrics metrics = calculator.calculate(snapshot);
        HealthStatus status = judge(metrics);
        if (status.needsAlert()) {
            alertService.send(turbineId, status);
        }
    }
}

evaluate方法只有六行，但读它的人能一眼看到整个流程。每个子方法各自独立，单元测试也能针对单个环节编写。

第三层：注释

注释不是翻译代码，而是解释”为什么”。

我踩过一个坑。IoTDB的写入接口，早期版本用的是同步写入，在高并发场景下会阻塞。我加了批量异步写入的逻辑，在方法上面写了一段注释：

1
2
3
4
5
6
7
8
9
10
11
12
13
/**
 * 批量写入风机时序数据。
 * 
 * 使用异步批量模式而非同步单条写入。
 * 原因：2025年Q3压测发现，同步写入在每秒2000条以上时
 * 会出现明显延迟（P99 > 800ms），切换异步批量后降至50ms。
 * 注意：异步模式下需要调用flush()确保数据落盘。
 * 
 * @param batch 一批风机传感器读数，建议500-1000条
 */
public void writeBatch(List<TurbineReading> batch) {
    // ...
}

这段注释里，”使用异步批量模式而非同步单条写入”是在说”做了什么决策”，后面是在说”为什么这么决策”以及”踩了什么坑”。

半年后另一个项目复用这个模块，接手的人看完这段注释就知道：异步是刻意选的，有压测数据支撑，调用的时候记得flush。不需要来问我，也不需要翻git log找commit message。

README：项目的”门口地垫”

README是项目的门面。一个项目的README质量，直接决定了别人对它的初始印象。

我现在的README模板长这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# 项目名

一句话说清楚这个项目是干嘛的。

## 快速开始

三步以内能跑起来。如果做不到，拆步骤。

## 架构概览

一张图 + 五行以内的说明。不要画UML十级图。

## 配置说明

每个配置项：名称、类型、默认值、说明。
用表格，不要用段落。

## 开发指南

- 如何本地运行
- 如何跑测试
- 如何提交代码（分支策略、commit规范）

## FAQ

别人问过你的问题，都记在这里。

这个模板并非凭空想出来的。是我在之前的项目里，每次新人入职问的问题都差不多——“怎么跑起来”、”配置在哪”、”测试怎么写”——然后我把这些问题整理成了FAQ，写进README。

后来新人入职第一天的Slack消息从”这个怎么跑”变成了”README我看了，有个地方不太确认”。

ADR：架构决策记录

ADR（Architecture Decision Record）是我2025年才开始用的东西。

以前做架构决策，讨论完就在脑子里的。换一个人来接手，完全不知道当初为什么这么选。

ADR的格式很简单：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# ADR-001: 使用IoTDB替代InfluxDB作为时序数据库

## 状态
已采纳（2025-08-15）

## 背景
风电场监控系统需要存储每秒2000+条传感器时序数据。
原方案使用InfluxDB，但在批量查询历史数据时性能不理想。

## 决策
切换到Apache IoTDB。

## 理由
- IoTDB的列式存储在宽表查询上比InfluxDB快3-5倍（实测）
- IoTDB支持SQL方言，团队学习成本低
- IoTDB是Apache活跃的开源项目，社区活跃

## 后果
- 需要迁移历史数据（约2TB）
- IoTDB的文档不如InfluxDB完善，部分高级特性需要看源码

每个ADR一个文件，编号管理，放进docs/adr/目录。不写长篇大论，一页纸说清楚。

我现在每次做技术选型，都会先写一个ADR草稿。好处是：写的过程会逼你想清楚”为什么”。如果你写不出三条以上的理由，说明这个决策可能还不够成熟。

踩坑：文档自动化工具不能替代人

2025年年底，我试过用Swagger/OpenAPI自动生成API文档。配置了注解，跑了起来，生成了一个漂亮的API页面。

然后发给前端同事，他说：”这页面我看了，每个接口都有参数说明。但我不知道这些接口的业务流程是什么——比如’启动风机’和’风机并网’是两个接口，但它们的先后顺序是什么？异常情况下怎么处理？”

Swagger能告诉你接口长什么样，但不能告诉你业务流程。自动生成的文档解决的是”有没有”的问题，解决不了”好不好”的问题。

后来我手写了一份API调用流程文档，用序列图画出核心业务场景，配上接口调用顺序和异常处理策略。前端同事说这份文档比Swagger有用十倍。

所以我的经验是：自动化文档工具（Swagger、Javadoc、TypeDoc）是底线，能确保API签名和参数说明不缺失。但核心业务文档必须人写，因为只有人理解业务。

每天一百字

最后一个习惯，听起来有点土。

我每天下班前花十分钟，在工程wiki上写一百字左右的技术笔记。内容很随意——今天踩的坑、解决的一个bug、学到的一个小技巧。

比如上周写的一条：

IoTDB的deleteStorageGroup()命令会删除整个数据库组，包括所有时间和元数据。执行前务必确认组名。今天差点删错，幸好有快照。（2026-06-18）

每天一百字，一个月就是三千字。这些碎片积累下来，写技术博客的时候翻一翻，素材就来了。而且写笔记的过程会强迫你把当天的技术问题再过一遍，加深记忆。

惯性需要打破

写文档这件事和写代码不一样，不会有编译器告诉你哪里错了。但文档质量直接影响团队效率。一个新人上手项目的时间、一个bug的排查速度、一次架构决策的可追溯性——这些都和文档有关。

我花了大概半年的时间才养成写文档的习惯。刚开始觉得是在浪费时间，后来发现不写文档才是在浪费时间——因为你省下来的时间，会在未来的某一天以”排查一个本该写在文档里的问题”的方式还回来。

今天回去翻翻你最近一次提交的代码，看看README。如果让一个陌生人来看，他能看懂吗？

本文由AI辅助生成框架，技术细节来自真实项目经验。