在PTT SOFT_JOB板上每隔一段時間都會有人問「程式要不要寫註解」這個問題。
在剛寫程式前半年覺得沒註解很可怕，也因為閱讀程式能力太弱，怕忘記或看不懂自己某一段邏輯在寫什麼，所以當時認為程式一定要有註解，自己也很常加不少沒用的註解。
沒用的註解包括以下冗余的註解，例如我寫過下面這樣。
Map<String, Integer> map = new HashMap<String, Integer>();
map.put("employee", 1); // 設定員工編號參數
if (...) {
...
if (...) {
} // end if
...
} // end if
或是修改紀錄。
/**
* 2019/11/17 修改了xxx功能 John
* 2019/11/19 新增了xxx功能 John
*/
public class Demo {
...
}
或是無意義的分隔界線。
////////////////////////// 下面是xxx /////////////////////////////
後來拜讀『Clean Code無瑕的程式碼』這本聖經後，又認為不應該寫註解，理由包括 ：
- 需要寫註解代表命名不好 ；好的類別名稱，方法名稱，變數名稱能夠替代註解並自我解釋的。
- 需要寫註解代表程式寫得不好，程式本身即最好的註解。
- 註解沒有隨著程式邏輯更新，導致註解與邏輯是不一致，後面的人看到不知道哪個才是對的。
- 散落在程式碼中的註解是一種干擾，降低程式的可讀性。
在之後的一段時間我成為程式命名即註解的忠實信徒，開始認為程式不該寫註解，寫註解代表程式命名及結構很糟，應該要讓名稱夠長夠自我解釋才是正確之道。
不過最近又認為註解有時還是必要的，畢竟程式是用英文撰寫，而英文又不是我們的母語，不是每個工程師英文都夠好能寫出命名良好的程式，團隊要達到上面透過好的程式命名來達到自我解釋的目標是有一定障礙，理想和現實總是有些差距。
此外除非在外商，要不然台灣本土的專案系統介面，功能，錯誤訊息等都是中文，如果再加上專業領域的各種術語，如果沒有使用註解輔助說明經常很難對得起來。
例如接手一個維護案子，從Mock畫面要去找到對應的Controller方法，如果此時Controller的RESTFul API方法上都沒有中文註解，而且類似名稱的功能又很多，這樣即使英文方法名稱夠好還是很難找到對應的方法。
另外一個支持仍要寫註解的理由就是，那些由一堆神人撰寫的偉大的函式庫和框架原始碼裡面也是有註解存在，那些大神的code提交前還要被眾人review，他們還是會寫註解來補充說明某個類別及方法在幹些什麼。
結論就是大方向仍是遵循Clean Code的原則，盡量讓程式自己去解釋自己，透過良好的命名來達到程式本身即註解，但對於無法一言以蔽之的邏輯，或是中文翻譯起來有困難的情況，加上適當地註解還是比較好。
所以問題不在於「要不要寫註解」，應該是「要怎麼寫好的註解」。
參考：
1 則留言:
不過最近又認為註解有時還是必要的，畢竟程式是用英文撰寫，而英文又不是我們的母語，不是每個工程師英文都夠好能寫出命名良好的程式，團隊要達到上面透過好的程式命名來達到自我解釋的目標是有一定障礙，理想和現實總是有些差距。
-------------------------------
同感，我也是一開始寫註解→→→→讀cleanCode後不寫註解→→→→還是寫比較好
張貼留言