程式碼的編排不是為了美觀，而是一種溝通。功能會隨版本更迭而改變，但你今天用格式建立起來的「易讀性」會長久影響每一位後來的開發者。好的編排讓檔案讀起來像一篇由上而下展開的報紙文章：先看到標題與大綱，再逐步進入細節。
🧠 Why It Matters
- 垂直開放性：用空白行分隔「每一組完整思緒」（一組相關宣告、一個邏輯區塊）。空白行給視覺喘息，避免程式碼擠成一堵文字牆。
- 垂直親密性：關係緊密的行要靠近。變數宣告盡量緊貼它第一次被使用的上方，讀者才不必回頭找定義。
- 由上而下的敘事（stepdown rule）：高層業務邏輯放檔案頂部，被它呼叫的私有輔助函式往下排。讀者先讀到大綱、再讀到細節——呼叫者在上、被呼叫者在下。
- 水平不要捲軸：保持行寬（約 80–120 字元），別逼讀者拉水平捲軸。運算子兩側留白，用空白多寡暗示優先級（
b * b - 4 * a * c）。
IMPORTANT
最重要的一條是團隊一致性勝過個人喜好。同一專案裡這個檔案 2 格縮排、那個 4 格，括號位置又各行其是，會大幅推高閱讀的認知負荷。好系統應該讓讀者一看到某種格式，就能直覺反應它的意義。
⚖️ Case Study
前 — 沒有段落、宣告離使用很遠、細節在前
function report(rows){
const HEADER="Sales Report";let total=0;let count=0;
// 一堆低階細節堆在最前面，主流程被淹沒
function fmt(n){return "$"+n.toFixed(2);}
for(const r of rows){total+=r.amount;count++;}
const avg=count?total/count:0;
return HEADER+"\n"+fmt(total)+" over "+count+" ("+fmt(avg)+" avg)";
}沒有空白行分段、total／count 宣告離使用很遠、低階的 fmt 擠在主流程之前——讀者得自己在腦中重排順序。
後 — 空白行分段、宣告貼近使用、大綱在上細節在下
function report(rows) {
const HEADER = "Sales Report";
const total = rows.reduce((sum, r) => sum + r.amount, 0);
const count = rows.length;
const average = count ? total / count : 0;
return `${HEADER}\n${money(total)} over ${count} (${money(average)} avg)`;
}
// 被呼叫的低階細節排在下方
function money(n) {
return `$${n.toFixed(2)}`;
}空白行把「標題／計算／輸出」分成三段；每個變數緊貼它的使用；主流程 report 在上、輔助的 money 在下——讀起來由大綱到細節，一氣呵成。
TIP
垂直排版該反映邏輯結構：縮排對應巢狀、空白行對應段落。當一個函式短到能一眼看完、且它呼叫的細節都在下方等著被展開時，整份檔案自然會「讀起來像一篇好文章」。
🔑 Takeaways
- 編排是溝通，不是裝飾——它決定後來者讀這份程式碼有多順。
- 垂直：空白行分段、宣告貼近使用、高層在上低層在下（stepdown）。
- 水平：控制行寬避免捲軸、運算子留白暗示優先級。
- 團隊一致性 > 個人風格；交給 Prettier／formatter 自動化，把爭論留給更重要的事。
- 短函式讓 stepdown 敘事成立——見 只做一件事。
No notes yet — jot your takeaways or Q&A here.