簡單英文
用最少的日常詞語說出主要內容，然後停止。讀者會開啟程式碼查看細節。
力求簡潔
- 開門見山：說明事物做什麼，若不明顯則加上為什麼。
- 省略程式碼或差異(diff)已顯示的內容：觸及的檔案、步驟的順序、程式碼處理的邊界情況。
- 使用業界的簡潔詞語：「移除未使用的圖示」，而非「移除那些沒有被用到的圖示」。
- 每個事實只說一次。
- 刪減詞語，而非事實。保留讀者理解問題所需的每個步驟，並說明後果：「該日期可能與 CI 製作發行的那一天不同」，而非「標題是在發行日之前寫的」。
保持清晰
簡潔不等於費解。
- 每個句子寫一個想法，並包含主詞與動詞。避免分號、謎語或標語，例如「無發行，無型別」。
- 將主詞放在前面，並指出誰在執行：「C++ 計算 X」，而非「X 被 C++ 計算」。
- 使用簡單時態，對仍為真的事使用現在式：「QML 永不在此重新評估繫結」，而非「從未被重新評估」。
- 將條件句寫為
如果 X，則 Y。 - 當名詞是前面的子句，或可能與多個名詞混淆時，重複該名詞而非使用「它」「它們」或「那些」。
- 保持「which」與「whose」子句簡短。若子句本身有長主詞，則獨立成句：「Debian 與 Ubuntu 的 Qt 套件沒有它」，而非「, which Debian's and Ubuntu's Qt packages leave out」。
- 明確說出否定：「忽略範圍外的數值」，而非「不取範圍外的數值」。不要透過受詞來否定：「該編輯未發出 updated()」，而非「該編輯沒有發出任何 updated()」。僅在「neither」之後使用「nor」。
聽起來像母語人士
文字必須讀起來像英語母語的開發者所寫。如果某個詞語讀起來像翻譯，請改寫它，即使改寫後多了一個字也無妨。
- 使用複合名詞，而非一連串的「的」：「應用程式設定」、「CSV 檔案對話方塊」、「Debian 與 Ubuntu 的 Qt 套件」。僅在沒有適當複合詞時才使用所有格，例如「該工作表的密度」，並且絕不連續使用兩個所有格。每個詞語最多允許一個「的」。
- 使用業界慣用動詞：「顯示」、「報告」、「修正」、「支援」、「處理」、「檢查」。不要讓程式碼變成能「告知」「回答」或「承載」的人。將「擁有」保留用於 C++ 意義上的所有權。
- 每個概念使用一個詞彙：選用「檢查」或「驗證」、「設定」或「選項」，並保持一致。
- 在列表中不要重複冠詞：「框架與刪除按鈕」。
- 用「必須」表示要求，用「可以」表示可能性。避免使用「應該」和「可能」。
- 使用「例如」，而非「e.g.」。使用美式拼寫。
- 刪除這些詞彙：「善用」與「利用」（改寫「使用」）、「為了」（改寫「來」）、「在...之前」（改寫「之前」）、「確保」、「簡單地」、「僅僅」、「容易地」、「無縫地」、「穩健的」、「強大的」、「全面的」、「功能」、「值得一提的是」、「透過此變更」、「旨在」、「讓你能夠」（直接說出事物及其動作）、「在底層」、「開箱即用」。
前後對照，來自真實的提交主旨：
| 之前 | 之後 |
|---|---|
| 將應用程式的設定保留在文件之外 | 不要在文件裡儲存應用程式設定 |
| Graph：告訴讀者何時匯出失敗 | Graph：報告匯出錯誤 |
| 新增 CardButton，物件頂端列的圖示按鈕 | 新增 CardButton，物件頂端列上的圖示按鈕 |
| Sampler：不取離散物件範圍外的數值 | Sampler：忽略範圍外的離散物件數值 |
| 停止一個帶有不同日期的發行說明之完整發行 | 在完整發行前檢查發行說明的日期 |
| 在 Ubuntu 26.04 上建置，並使用其 Qt 套件 | 在 Ubuntu 26.04 上建置，並使用其 Qt 套件 |
依文字類型
提交訊息
- 將主旨寫成一個簡短的祈使句，在不看差異(diff)的情況下也能理解：「將文件數值限制在設定面板範圍內」，而非「將文件的數字保持在面板範圍內」。
- 一個提交只做一件事。如果內文需要第二個主題，請分割提交。
- 內文開頭先說明程式碼現在做什麼，然後簡短說明原因。
- 用「同時也」標記主旨之外的事實：「兩個讀取同時也跳過未知的金鑰，因為較新的版本可能會加入一些。」
- 省略讀者已知的背景資訊。不要重述差異(diff)或為變更辯護。
程式碼註解
- 預設情況下不寫註解。僅在說明程式碼未顯示的原因、隱藏的不變量或解決方法時才撰寫。
- 分別用一句簡短的句子說明程式碼做什麼、其後果為何以及為什麼這麼做。跳過程式碼已顯示的部分。
- 指名 API 並避免使用隱喻。使用祈使句沒問題：「跳過相同寫入：它們仍會更新 mtime」。
- 寫下你會對問「為什麼有這個？」的同事所說的註解。指出具體效果，例如「xmin 保持左側對齊」，而非總結如「邊界停留在它們的位置」。
範例：
- 之前：
// 一個垂直列表隱藏其寬度，因此樣式會繪製一個漂浮的把手 - 之後：
// 一個垂直的 ListView 將 contentWidth 保留為 -1，這會讓樣式將其呈現為折疊的把手 - 之前：
# 執行者的 glib 和 libsystemd 需要其新的 glibc，因此 AppImage 使用主機的 glib 和 libdbus。linuxdeploy 仍複製僅它們需要的程式庫，因此列表也列出了那些 - 之後：
# 不要捆綁 glib、libdbus 及其相依項目。AppImage 會載入主機的版本。Ubuntu 26.04 版本需要 glibc 2.43，這是較舊的發行版所缺乏的。
文件
- 描述程式碼目前的運作方式。說出事物名稱及其用途，並指向包含細節的檔案。
- 將三個或以上的並列項目放入項目符號列表。
- 將樣式、模組和識別碼名稱放入反引號：
FluentWinUI3。 - 用「目前」或版本號標記關於可能變更的第三方軟體的事實：「Debian 與 Ubuntu 的 Qt 套件目前沒有它。」
錯誤訊息： 發生什麼事、原因（如果已知）以及該怎麼做。不要道歉。
工具提示： 該小工具設定了什麼。
給代理的指示： 每個句子一條規則，先寫條件。
保留不變
程式碼、識別碼、命令、路徑、引用的訊息、產品名稱，以及按鈕、分頁、欄位和選單項目的名稱。
交付前
以讀者的身分將文字讀一遍。刪除對該讀者無幫助的每個句子。檢查每個剩下的句子第一次閱讀就能正確理解，並且聽起來像一般的英語。
如果你在聊天中解釋過相同的事情，請比較兩者。如果聊天版本更清晰，請使用它。