[Programming] 不被誤解的名稱

最近閱讀了易讀程式之美一書，在不被誤解的名稱此章節提到幾個重點

1. 反覆思考名稱，自問別人會怎麼解釋這個名稱
2. 對於邊界的極值而言，最清楚的方式是在名稱前面加上max_或min_
3. 選擇boolean變數或回傳booleab值的函數名稱時，必須確保能清楚表示true / false的意義
4. 一般來說，加上is / has / can / should 可以讓boolean value更加明確
5. 避免在名稱中使用否定描述，如disableSSL，改用useSSL會比較容易閱讀且簡短
6. 最好的名稱是最不容易被誤用的名稱，閱讀程式碼的人能夠清楚了解撰寫程式的人的意圖。不幸的是，許多英文單字在程式碼都會有兩種以上的解釋，如filter、length以及limit
7. 在決定名稱前，要從反向思考，想像可能造成的誤解，最好的名稱能夠盡量避免誤會
8. 對於定義數值的上下限，max與min是很有幫助的prefix；對於閉區間，first與last也是十分合適的prefix；對於半開放區間，begin與end是符合使用慣例的好選擇
9. 注意使用者對特定單字的預期，如使用者會認為get與size是lightweight accessor

Example
1. 對於邊界的極值而言，最清楚的方式是在名稱前面加上max_或min_。以切字串為例，即長度第15個字以後以...表示，如"撰寫程式時，應該將讀者理解所需的時間降到最短"此段字串要回傳"撰寫程式時，應該將讀者理解所需..."

如在main method裡面分別呼叫clip與truncate兩個methods

1 2 3

String str = "撰寫程式時，應該將讀者理解所需的時間降到最短"; test.clip(str, 15); test.truncate(str, 15);

以下是clip method的第二個parameter的命名

1 2 3

public String clip(String text, int length) { return text.substring(0, length).concat("..."); }

以下是truncate method的命名，改成用maxLength，相較於前者，較為明確、清楚

1 2 3 4

// 改成maxLength，會更加清楚明瞭 public String truncate(String text, int maxLength) { return text.substring(0, maxLength).concat("..."); }

2. 加上is / has / can / should 可以讓boolean value更加明確

1 2 3 4 5

public Boolean authenticate(User user) { // do authentication, if failed Boolean checkPassword = Boolean.FALSE; return checkPassword; }

若將checkPassword改成如下，意義會更加直覺

1 2 3 4 5

public Boolean authenticate(User user) { // do authentication, if failed Boolean userIsAuthnticated = Boolean.FALSE; return userIsAuthnticated; }