將宣告組織成區塊

class FrontendServer{
  public:
  FrontendServer();
  void ViewProfile(HttpRequest* request);
  void OpenDatabase(string location,string user);
  void SaveProfile(HttpRequest* request);
  string ExtractQueryParm(HttpRequest* request,string param);
  void ReplyOK(HttpRequest* request,string html);
  void FindFriends(HttpRequest* request);
  void ReplyNotFound(string location,string error);
  void CloseDatabase(string location);
  ~FronttendServer();
};

程式碼不太嚇人，但排版方式對理解沒有任何幫助，可以拆分成幾個有邏輯性的群組：

class FrontendServer{
  public:
  FrontendServer();
  ~FronttendServer();
  
  // Handlers
  void ViewProfile(HttpRequest* request);
  void SaveProfile(HttpRequest* request);
  void FindFriends(HttpRequest* request);
  
  // Request/Reply Utilites
  string ExtractQueryParm(HttpRequest* request,string param);
  void ReplyOK(HttpRequest* request,string html);
  void ReplyNotFound(string location,string error);
  
  // Database Helpers
  void OpenDatabase(string location,string user);
  void CloseDatabase(string location);
  
};

顯然更容易理解。

區分程式碼「段落」

寫作時會將文章分為不同的段落：

• 將相似內容放在一起與其他概念分開。
• 提供視覺上的「墊腳石」-讓讀者清楚知道目前的位置。
• 提供段落的索引。
  出於同樣目的，程式碼也應該分成多個「段落」：

# 匯入使用者的email聯絡人並將資訊與系統中的使用者對應
# 再顯示出還沒不是朋友的使用者清單
def suggest_new_friends(user,email_password)
    friends = user.friends()
    friends_emails = set(f.email for f in friends)
    contacts = import_contacts(user.email,email_password)
    contact_emails = set(c.email for c in contacts)
    non_friend_emails = contact_emails - friend_emails
    suggested_friends = User.object.select9email_in=non_friend_emails)
    display['user'] = user
    display['friends'] = friends
    display['suggested_friends'] = suggested_friends
    return render ("suggested_friends.html",display)

如果將各步驟程式碼做區分會有很大的幫助：

def suggest_new_friends(user,email_password)
    #取得使用者朋友的email
    friends = user.friends()
    friends_emails = set(f.email for f in friends)
    
    #由使用者email帳號匯入所有email
    contacts = import_contacts(user.email,email_password)
    contact_emails = set(c.email for c in contacts)
    
    #找出還不是使用者朋友的email
    non_friend_emails = contact_emails - friend_emails
    suggested_friends = User.object.select9email_in=non_friend_emails)
    
    #將清單顯示在頁面上
    display['user'] = user
    display['friends'] = friends
    display['suggested_friends'] = suggested_friends
    
    return render ("suggested_friends.html",display)

在每段上方加入摘要性註解，也有助於瞭解程式碼。

Reference

• <<易讀程式之美學－提升程式碼可讀性的簡單法則 >>(The Art of Readable Code)