核心觀點#

程式碼的編排（Formatting）不僅僅是為了美觀，它是種溝通方式。
作者 Robert C. Martin 強調，程式碼的可讀性會直接影響可維護性。
功能可能會隨版本更迭而改變，但由編排風格建立的「易讀性」與「清晰度」卻會長久影響後續開發者。

程式編排是專業開發者首要的溝通工具。
一個良好風格應有一致性與流暢度，讓讀者能信任所看到的格式都代表著相同意義。

垂直編排 (Vertical Formatting)#

垂直方向的編排重點在於引導讀者的閱讀視線，讓程式碼像報紙文章一樣，由上而下自然展開。

1. 善用空白行區隔思緒#

程式碼也是由不同「段落」組成的。
在軟體開發中，每組完整思緒（例如一組相關的變數宣告、邏輯區塊）間，應加入空白行。

• 垂直開放性 (Vertical Openness)： 空白行能將不同概念分開，讓視覺獲得喘息，
  避免程式碼變成一團擁擠文字牆

2. 垂直密度與親密性#

如果說空白行是用來區隔不同概念，那麼緊湊程式碼行則用來表達「親密關係」。

• 緊密相關應靠近： 關係緊密的程式碼行（例如相關的運算邏輯）應出現在同個視線範圍內，
  不要強迫讀者在檔案中跳來跳去尋找定義
• 變數宣告 (Variable Declaration)： 變數應盡可能緊跟在它被使用的上方，
  這樣讀者不需回頭尋找該變數定義

3. 函式的排列順序#

為了讓程式碼讀起來像順暢文章，我們應遵循「由上而下」的敘事規則：

# 好的結構：像讀故事一樣，先看到大綱，再看到細節

def main_task():
    setup_environment()
    execute_process()
    cleanup()


def setup_environment():
    # 實作細節...
    pass


def execute_process():
    # 實作細節...
    pass


def cleanup():
    # 實作細節...
    pass

水平編排 (Horizontal Formatting)#

水平編排的目標很簡單：不要讓讀者使用水平捲軸。
儘管現代螢幕越來越寬，但保持簡短行寬（建議 80-120 字元）仍是最佳實踐。

1. 運算子與留白#

透過在運算子周圍加入空白，可以強調運算的優先級與區隔。

• 強調運算子： 在賦值符號 = 或運算符號 +、- 兩側加上空白，能讓程式碼更清晰
• 表達優先權： 透過空白多寡表達數學上的優先順序（先乘除後加減）

# 擁擠且難讀
b = b * b - 4 * a * c

# 清晰且強調結構
b = b * b - 4 * a * c

團隊規則 (Team Rules)#

最重要的一條規則是：團隊一致性勝過個人喜好。

如果一個專案中，某檔案用 2 格縮排，另個用 4 格；或者括號位置不統一，會大大增加閱讀認知負擔。 好的軟體系統應讓讀者在看到某種格式時，就能直覺反應出其代表意義。

“A good system consists of a set of documents that read nicely.”