上周帮同事看一个云同步 SDK 的 bug，翻到核心上传模块，满屏都是这样的注释：
// 这里处理上传逻辑
// TODO: 后续优化
// 2023-05-12：加了个判断
// 注意：这个值不能为 null结果花了半小时才搞懂，那段“不能为 null”的判断，其实是为了绕过某家云厂商 API 在空字符串时返回 400 的坑——可注释里根本没提厂商、没写场景、也没标版本号。
注释不是日记，是给下一个人留的路标
在云存储这类多人协作、长期维护的模块里，注释常要扛三件事：跨团队对接（比如前端传参格式变了）、灰度上线后回溯（比如某次升级后断点续传失败）、还有半年后你自己凌晨三点被叫起来查日志。这时候，“// 处理上传”不如一句“// 阿里云 OSS PutObject 要求 x-oss-server-side-encryption 必须显式设为 AES256 或空字符串，否则 400”。
几条踩过坑才信的实操规矩
函数开头不写“功能描述”，就写“为什么这么写”：
比如上传前校验文件大小，别只写“校验 size”，而是写“校验 size ≤ 5GB：OSS 单文件 PUT 上限，超限自动切片（见 UploadChunker）”。
魔数必须带上下文：
云服务常有各种阈值，像 if (retryCount > 3)，得补一句注释：
// 重试 3 次：腾讯云 COS 临时凭证有效期 900s，单次请求耗时预估 ≤ 300s，预留 3 次容错删代码比写代码更需要注释：
曾经有个项目把 S3 的 CopyObject 替换成了分块上传，但旧注释还挂着“用 CopyObject 实现秒传”。后来新人照着注释改逻辑，结果在跨区域桶上直接失败——因为 CopyObject 不支持跨 region。现在我们删代码时会留一行：
// 移除 CopyObject 调用：S3 跨 region 不支持，且大文件易触发 30s 连接超时（见 2024-03 运维周报 P12）顺手记两笔小习惯
• 用 FIXME: 标出已知缺陷（比如“FIXME: 当前未处理七牛云 signature 过期重签逻辑”）；
• 时间戳写完整日期，不写“昨天”“上周”；
• 提到云厂商时，写全称+缩写，比如“华为云对象存储（OBS）”——新来的同学不一定知道 OBS 是啥。
注释写得清楚，下次你翻自己半年前的云上传模块，就不会对着 // 这里有个 trick 发呆了。