swe-knowledge

swe-knowledge — 軟體工程的 Definition of Done

這裡放的是所有增量共用的完成條件。跟每張單獨有的驗收條件（acceptance criteria）分得很 開：AC 寫在那張單凍結的 assertion 裡，DoD 寫在這裡。一張單可以通過全部 AC 卻沒有 done—— assertion 全綠但改動還躺在預設分支上、沒有任何人看得到它，就是那個情況。

所以這幾條不要抄進任何一張單的凍結區。抄進去等於每張單都重簽一次同樣幾行不承載新資訊的 東西，而漏抄的那一張就靜默地少了一條完成條件。

五條

1. 改動住在一條 branch 上，不躺在預設分支。 開的時機是「判定要立案之後、動手之前」—— 一個還沒開工的成功定義直接躺在預設分支上，等於它已經是既成事實。

2. 有一個 PR。 PR 開出來就是實作完成：它是那份改動變成可被別人看見、可被判定的 東西的那一刻。沒有 PR 的改動不管本機多綠都還沒 done。

3. 判定過才進預設分支。 進去的路徑是那個 PR，不是直接推。

4. push 之前，本機跑完跑得動的驗證。 type check、lint、單元測試、受影響路徑的冒煙。 把 CI 當第一道防線等於把 reviewer 當驗證工具。

5. reviewer 提的每一條，處置回到那條意見上。 不是「有沒有處理」——是提出者拿不拿 得到那個處置。他看的是他留言的地方，回在別處他收不到。

   處置有四種：照做、回覆說明為什麼不照做、拒絕、另外開單。照做不是預設。「處置」這個 字是中性的，而它常被讀成「照做」。一條意見可以是對的、而仍然不該在這一輪做；也可以是 這個 repo 根本不做那件事。讀成「照做」的話，這一條會把每一則意見都變成一次施工。

   每一串都算，nit 也算。 「妥善處理」的量法是：每一串的最後一則是作者，而且那一則說出了 四種處置裡的哪一種。標成 nit 的意見只是提出者在說「這條不擋你」，不是在說「這條不用回」。

第 2 條有一個這個 repo 自己的教訓：2026-08-03，「開 PR」這個能力在腳本歸位時被刪掉，因為 它在三站裡沒有主人；43 分鐘後有人寫了一句跟腳本矛盾的散文把洞蓋住，於是「PR 算不算完成」 有兩個互相矛盾的答案在流通。現在它有主人了，就是這一條。

第 5 條是同一個形狀又發生了一次。2026-08-11：一個 PR 收到三位 reviewer 的意見，全部查證、 修掉、assertion 重跑全綠，也回了另一個系統的訊息串——但那個 PR 上一則回覆都沒有，是人自己 發現的（「我好像沒有在 PR 上看到你怎麼處理的」）。偵測有主人（誰欠我回覆、誰欠我審查， 都有東西在算），動作沒有主人。而「還沒被 approve」這個狀態，跟「我還沒動手」長得 一模一樣。

在程式碼裡，「你寫下的話」長成什麼樣子

engineering 那條「送審之前把自己寫下的話跟行為對一遍」在這一類工作裡有具體形狀。這幾樣 都是對行為的主張，都會跟實作分開演化，而編譯器與測試都不會抓：

• doc-comment 的第一句——通常是最早寫下的，也最可能是舊設計的化石。
• 型別宣告（參數型別、回傳型別、介面欄位）——宣告成數字就不能送出字串。它是契約， 不是提示；改了寫入路徑要回頭看宣告。
• 名字——一個叫「處理中」的狀態要真的在事情處理中的時候是真的。
• 形狀——把等待用的結構套在一個不會等待的呼叫上（例如包住一個同步呼叫），會讓一段 沒有等待的程式碼長得像在等待，而讀的人依樣相信它。

第 4 條那句「本機跑完跑得動的驗證」的另一半就是這個：跑得動的用跑的，跑不動的用讀的。 一句說謊的 doc-comment 跑不出紅燈，它只會在下一個人依它行事的時候生效。

所以寫的時候就要讓它值得被讀：

• 新增或修改的 function 要有 doc-comment（TSDoc / JSDoc / Google-style docstring / shell function header），說明它做什麼、參數與回傳值是什麼。既有沒動的不強制回填——上面 那句「最可能是舊設計的化石」講的就是它們，補一句猜出來的比空著糟。
• 帶業務意義的 literal 抽成有名字的常數，名字說不完的在宣告處補一行。名字也是一句 對行為的主張，同一條規矩適用。純視覺數值（padding、gap）與 aria-label 這類不強制。
• Inline comment 只在「為什麼」不自明時寫，一短行。 逐行解說「做什麼」是會說謊的 雜訊：它貼著那一行，那一行改了它不會跟著改。