note for "The Art of Readable Code" - CH3 & CH4

CH3, Names That Can’t Be Misconstrued

Actively scrutinize your names by asking yourself, “What other meanings could someone interpret from this name?”

1. 比如results = Database.all_objects.filter("year <= 2011")的結果是<= 2011還是過濾了<= 2011的結果？如果用select()或exclude()會更為明確



2. 對於含有邊界意思的, 可以使用"min_"與"max_"加以辨識.



3. 對於閉區間使用first與end, 而半開放區間使用begin與end, 因為這些已經在C++中成為慣例了.



4. 關於bool則可以加上is, has, can, should等意思會更明確, 如

bool user_is_authed = true
會比下面這行更容易被明確
bool read_password = true




5. get*()(開頭的function), 通常指直接回傳內部成員, 如果還需要計算, 最好改用compute*()或count*(),

CH4, Aesthetics

這個章節是在講述, 好的排版會讓人更容易看懂code, 以下是我摘要的幾個範例

1. 給予參數一些註解

public class PerformanceTester {
   // TcpConnectionSimulator(throughput, latency, jitter, packet_loss)
   //                            [Kbps]   [ms]     [ms]    [percent]
   public static final TcpConnectionSimulator wifi =
       new TcpConnectionSimulator(500,     80,     200,     1);
   public static final TcpConnectionSimulator t3_fiber =
       new TcpConnectionSimulator(45000,   10,       0,     0);
   public static final TcpConnectionSimulator cell =
       new TcpConnectionSimulator(100,    400,     250,     5);
}



2. 讓參數對齊

CheckFullName("Doug Adams"  , "Mr. Douglas Adams" , "");
CheckFullName(" Jake Brown ", "Mr. Jake Brown III", "");
CheckFullName("No Such Guy" , ""                  , "no match found");
CheckFullName("John"        , ""                  , "more than one result");



3. 段落分明

def suggest_new_friends(user, email_password):
  # Get the user's friends' email addresses.
  friends = user.friends()
  friend_emails = set(f.email for f in friends)

  # Import all email addresses from this user's email account.
  contacts = import_contacts(user.email, email_password)
  contact_emails = set(c.email for c in contacts)

  # Find matching users that they aren't already friends with.
  non_friend_emails = contact_emails - friend_emails
  suggested_friends = User.objects.select(email__in=non_friend_emails)

Consistent style is more important than the “right” style. 無論你是用什麼coding style, 一致性會比你用“對”的style更重要.

參考資料:
• The Art of Readable Code