Android到底要不要寫註釋

先來靈魂一問，你們平時開發，寫不寫註釋的都，我先來，方法加註釋？不存在的。類註釋？想多了。網絡請求解析實例元素註釋，這個確實要寫點，否則都不知道是個什麼玩意。不要說什麼字段名就是最好註釋，這個的前提是，用詞準確而且閱讀理解的水平相近，否則，那就是呵呵。

那麼你們爲何不愛寫註釋，至少我本身不愛寫就幾個緣由，1 懶。2 快速迭代就夠煩了，誰還折騰這個，bug都還沒改完呢。3 光我一我的寫，其餘小夥伴不寫也沒勁啊，我本身寫的代碼，寫不寫註釋我本身都還有點印象，我寫了註釋，只是方便其餘人理解，我本身接手修改別人負責的內容時，仍是沒註釋啊，註釋寫得不夠明白的不也折騰。4 註釋實際上是須要更新的，尤爲是方法註釋，某個版本修改某個功能後，若是註釋忘記更新，那也是會有誤導性的，尤爲是註釋參數須要足夠明確參數範圍和用法。

可是註釋真的能一點都不寫嗎，那確定不行的，坑人坑己，時間長了本身坑本身，因此我總結了下，在最懶的狀況下，有這麼些註釋是值得去寫的，並且基本是一次性的，建立的時候順手寫上徹底不礙事，而且最好強制同項目小夥伴嚴格執行。結合實際來講，我常常遇到後臺，測試，產品，拿着手機就過來問，這個頁面的這個啥能不能改，這個頁面用到了哪些接口..等等等等。通常來講，若是這個頁面恰好是本身作的，那還有點印象，在哪一個包，哪一個Activity或者Fragment，但若是不是，那就只能，等等我先找找，每次都這樣不累麼。其實基本上大部分應用，每一個activity或者fragment對應的都是特定職能的頁面，並且大多數頁面都是有標題的，好比什麼，"設置"頁面，"修改XX密碼"頁面，"關於"頁面等等。因此，在建立類的時候，順手寫上是值得且有用的。 好比：

/**
 * 總資產頁面
 */
 public class TotalAssetActivity extends BaseActivity{}
/**
 * 歷史消息頁
 */
public class FragmentHistoryMessageHome extends BaseFragment{}
複製代碼

諸如相似，這樣之後無論誰找來，只要主題明確，在studio中ctrl+h一把就能快速定位

重點就是註釋明確不要瞎寫，結合應用體現中心主題，別瞎搞很差理解的就行。

第二類非寫不可的註釋，那就是網絡接口定義註釋，仍是實際問題。 後端同事：能不能幫我看看這個接口哪些頁面會調用到。 我：？？什麼接口。 同事：查詢XX數據的接口。 我：哦，等我先找找這個接口定義在哪。 而後找到後再來一頓ctrl+g搜索一把，最後找到定位。

那麼若是加了註釋，會不會方便不少呢。因爲大部分接口職責單一的特殊性，其實道理和activity同樣的，建立的時候，就決定了這個接口是幹嗎用的，需求會明確到那些界面會使用，而且這個做用後期並不大可能修改，涉及到修改的，一般考慮兼容性會選擇新增功能接口，因此這個註釋也是能夠在一開始就肯定的。 好比

/**校驗短信驗證碼
   * @since v1.5
   * @see com.xxx.xxx.ui.dialog.sms.CommonSMSCodeDialogEventHandler
   * @see com.xxx.xxx.ui.fragment.VerifySMSFragment
   */
  public final class CheckSMSCodeRequest extends BaseRequest<CheckSMSCodeResult> {}
複製代碼

主要推薦兩個元素 1 功能描述，這個接口用來幹嗎的寫清楚（特別強調，推薦寫在文檔註釋第一行） 2 文檔註釋中的 @see 標記，其實改爲{@link}也能夠。使用see標記，可以使文檔註釋直接點擊跳轉到指定的頁面類，並且寫註釋的時候這個過程是便捷化的，並不用一個字一個字敲，基本向上面的，打個@see verify，studio就智能引出可選類了，誰用誰知道。 可選標記@since 這個是我的習慣問題，哪一個接口，是哪一個版本迭代才增長的，標記一下，順手的事，方便過後分析，由於會有同類型接口在某個新版本加入，用來逐步替代某個版本的老接口，可是有些人又不清楚的，會須要區分，同時老接口打上@Deprecated 。 當全部定義的接口都嚴格註釋後，新世界來了，android studio下選中代碼主包，而後來這麼一下

別忘了加參數 -encoding utf-8 -charset utf-8 就會獲得一份傳統的java doc文檔，沒有註釋的類咱們無論，我接口都放在同一個子包下，程序包中選中接口所在包，隨便選一個接口類切換到程序包，就會看到

而且點擊進去後，能夠很方便的看到該接口用在了哪兩個類

結合一開始說的頁面註釋，已經方便不少了，這樣至少之後別人問起來，或者本身找起來，再也不那麼狗血。 最後說一下，定義接口解析實例對象的字段屬性，也必定要註釋，否則，誰來都受不了，哪怕只是漏一個，之後都有多是坑，人員來來去去，徹底不知道這個字段是什麼意思，要去翻用在哪，怎麼用，來反推這個字段的意義，賊坑啊。

最後，願你們接盤項目都有註釋，只要人人作到了寫好註釋，那在填坑的路上，不至於一腳踩得太深。