V02 註解本體的內容與註解的放置

註解要怎麼寫才是理想的？在網路上能找到一些不同的說法。比較普遍接受的說法是不要記載程式碼怎麼寫的，而要記錄為了什麼目的而寫這些程式碼；因為註解是為了讓其他人快速地看懂自己為什麼要這樣寫。對於這個看法我沒有異議，方法有自己必須達成的目標，方法內的一連串註解是達成目標的分解動作，一組詳細記錄的註解其作用有如該方法的SOP般讓所有人都能很快地看懂怎麼樣來完成。

註解以精簡為目標，但是在較艱深的場合還是附上簡短的範例說明較為理想。如果把人腦視作一部電腦，撰寫某段程式碼後寫出的註解就像是把當時的想法匯出為文字敍述，驗證註解內容是否恰當的一種方式，就是經過較長一段時間忘卻後讓原撰寫者看自己原來所寫的註解，倘使能夠讓自己完全回憶起當時的情景就是滿足所需的註解。

目前Class、Method與Data的Java Doc註解，以及程式上的Comment都跟著程式碼走。前面的Java Doc只存在於靜態說明的地方，即使屬性加多後行數增多，並不至於影響閱讀；但是Comment一般都要求越簡短越好，用我的方法製作Comment後勢必使得程式碼間的間隔拉大造成不易閱讀的現象，這並不符合普遍的需要。

龐大的Comment或許可以脫離程式另外存在？這是讓程式碼變回較易讀的方法之一，但是Comment與程式分離之後必須有自己的管理機制，同時還要建立Comment與程式碼的關聯。程式碼是非常易變的東西，建立在易變的基礎而且必須另外同步更新Comment勢必浪費非常多的時間。顯而易見地，這是一個蠢解法。

既然目的是在擁有詳細的註解時維持程式碼的可讀性，那麼可以學習Eclipse作法，在Java編輯器上把Comment區塊縮減為一行。開啟一個Class後其實我們可以發現有很多地方可以收合，像是最前面的版權宣告區塊、所有的Java Doc註解與Method的程式本體都是如此，但是對於Comment就沒有這樣的功能。改寫Java編輯器使之對Comment也有收合與展開的功能，就可以達成目的。