先來說說何謂Self-documented Code
Self-documenting的程式碼或使用者介面遵從命名規範及結構化程式設計規範 ，進而讓使用者可以在使用系統上不需要花時間參照其他文件或是註解。
也就是說，Self-documenting Code的中心思想就是:
寫出一看就懂的程式碼!
Well-documented Code??
意思就是藉由大量的註解來讓使用者來了解程式碼的用意即用途。
選擇哪一種方式其實沒有標準答案，但是先來深入了解一下Self-documenting Code的理念。
何謂好的Self-documetned Code?
一個好的程式碼除了沒有錯誤，邏輯清楚之外，大型開發時因為有多人協作的關係，讓程式碼易讀就變得十分重要!
一個好的Self-documetned Code有下列幾項特點:
1. 每個物件或是方法都只有一個特定的用途(原子函數)
這邊重點是”一個”! 要細化函數的用途，每個函數只會有一種操作。
如果可以做到這點，那註解的意義就不大了，除非有副作用。(指得是會產生主用途以外的其他影響)
*原子函數: 指將函數的用途細分，如果一個函數可以做到兩件事，那可以考慮把函數再往下拆分成兩個函數。
2. 選擇有意義的名稱
這一點十分重要!
例如有個方法叫做sort，那你大概就可以猜到這個方法是要用來排序的，也就是說你直接看名稱就可以知道用途，不用依靠文件或是註解!!
例如:
如果是有邏輯性的內容要體現出該邏輯性，例如isEmpty, isRunning。 如果是名詞的話就用名詞，例如user, userName等等，要能表示出名詞含意。
3. 程式如何運作很明顯，不須大量註解
如果可以遵從以上規範，那不需要額外輔助的文件你也可以知道程式要如何運作，這樣除了節省了開發者參照文件的時間，也降低了之後要維護的成本。
4. 把註解當成輔助，添加的註解應該給程式碼帶來附加價值 如果程式碼本身無法繼續提高可讀性，這時才選擇使用註解，且添加的註解應該要可以為程式碼帶來價值!
所以要選擇哪個呢?
其實蠻明顯的，最好的方式應該是好好照著規範撰寫程式碼，然後真的需要註解的時候再寫註解，Best of both worlds!