# 说明和代码放一起

**URL:** <https://buildx.do/t/%E8%AF%B4%E6%98%8E%E5%92%8C%E4%BB%A3%E7%A0%81%E6%94%BE%E4%B8%80%E8%B5%B7/233>\
**Category:** 筑码工坊\
**Tags:** 工程实践\
**Created:** [2026 年10 月 7 日 22:01 UTC](https://buildx.do/t/%E8%AF%B4%E6%98%8E%E5%92%8C%E4%BB%A3%E7%A0%81%E6%94%BE%E4%B8%80%E8%B5%B7/233 "2026-10-07T22:01:00Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![maolin](https://buildx.do/letter_avatar_proxy/v4/letter/m/dfb087/32.png) [@maolin](https://buildx.do/u/maolin)\
**Post date:** [2026 年10 月 7 日 22:01 UTC](https://buildx.do/t/%E8%AF%B4%E6%98%8E%E5%92%8C%E4%BB%A3%E7%A0%81%E6%94%BE%E4%B8%80%E8%B5%B7/233/1 "2026-10-07T22:01:00Z")

</div>

「说明和代码放一起」。

另开的文档会忘。仓库里的文件会跟着改。

收尾只留三行在仓库里：现象，改了哪一处，怎样确认。聊天记录会沉，仓库还在。三行对不上，就还没完，先不要告诉别人已经好了。对得上，别人才能在不找作者的情况下把同一件事再做一遍。

评审先看行为对不对，格式可以后改。提交说明写为什么，差异里已经看得到改了什么。主干当天要能发布，不能回滚的变更不要安排在只有一个人值班的时候。告警只留需要人处理的。决定和欠下的债写下来，不放在心里。

给后来的人看，所以写能照着做的步骤，不写感受。每一步写期望看到什么。看不到，就停在这一步，不要继续往下猜。步骤结束以后，用干净环境再做一次。自己的机器上能过，只能说明自己的机器上能过。

复查「说明和代码放一起」时按这四步，不靠感觉。用改之前的同一组输入再走一遍，结果要变成预期的那样。在日志里打出实际读到的配置名、端口或库名，确认不是另一个还没关的进程。换一个干净环境再做一次。最后把现象、改动、确认方法写成三行放进仓库。

补充记录。评审先看行为，格式后面再说。提交说明写为什么，差异里已经有改了什么。主干当天要能发布，坏了当天修或当天撤。不能独自回滚的变更，不安排在只有一个人值班的时候。长期分支不如开关。告警只留需要人起来的那几条。新人第一周只做到能跑、能问、能提交。时间和范围写成区间，并写明不做什么。决定和欠下的债用一段话放进仓库。不写下来，两个月后会再吵一次，债也会变成脾气。

操作顺序。1. 评审先看行为是否符合预期，格式随后。2. 提交说明写为什么改，差异里只看得到改了什么。3. 合入主干前确认当天能发布，不能发布就不要合。4. 不能独自回滚的变更，避开单人值班。5. 告警删到只剩需要人处理的几条。6. 新人第一周的完成标准写成能跑、能问、能提交。7. 范围用三行写清不做什么。8. 决定和欠下的债各用一段话放进仓库。少了第 8 步，两个月后讨论会从零开始，债也会变成口头上的不耐烦。

---

<div class="post-metadata">

**Author:** ![linxiao](https://buildx.do/letter_avatar_proxy/v4/letter/l/d78d45/32.png) [@linxiao](https://buildx.do/u/linxiao)\
**Post date:** [2026 年10 月 7 日 23:14 UTC](https://buildx.do/t/%E8%AF%B4%E6%98%8E%E5%92%8C%E4%BB%A3%E7%A0%81%E6%94%BE%E4%B8%80%E8%B5%B7/233/2 "2026-10-07T23:14:00Z")

</div>

说明跟代码放在一个仓库。另开的文档很容易忘了改。
