[Coding] 02-Android Studio 中的 Javadoc-提升程式碼的可讀性

發表於 更新於 閱讀次數：

情境

註解是為了讓人閱讀的，無論是其他同事還是兩個禮拜後的自己。因此，註解必須清晰地描述方法的參數和作用。本文將著重於如何在 Android Studio 寫好用的註解，和方便快速的建立註解。至於 Javadoc 詳細的撰寫規範可以參考文末資料(How to Write Doc Comments for the Javadoc Tool#A Style Guide)。

本文可隨意搭配有撰寫 Javadoc 的專案使用，或參考下方 Demo 程式中的 Javadoc。
Demo 程式：GitHub: https://github.com/dreambo4/android-basics-kotlin-mars-photos-app

Javadoc 註解介紹

根據Oracle的官方文件，註解分為兩種：

  • 實作註解(Implementation Comments): 主要用於註解程式碼或對具體實作進行說明。使用 /*...*/ 和 // 符號，與 C++ 的註解相似。
  • 文件註解(Documentation Comments): 用於描述程式碼的規範。是 Java 特有的，使用 /**...*/ 符號。

在 Android Studio 中使用

在 Android Studio 中提供方便查看註解的方式，只要將滑鼠指到一個物件、變數或方法上，就能查看相關的註釋內容。寫文件註解的好處就是，開發時不需要再一層一層點回變數宣告處，即可確認變數用途。

但要注意的是，只有文件註解的寫法，才會被解析成 Documentation。

  • 實作註解，比較適合用於程式碼中的說明。
  • 文件註解，適合寫類別、成員變數、方法的說明。
    兩種註解寫法

在 Android Studio 很方便的是，只要輸入 /**，按下 Enter 鍵，就會自動自動建立文件註解模板。
文件註解模板

後記

另外，若專案的 Javadoc 寫得夠完整，還可參考這篇教學，將整個專案的文件註解匯出。

參考資料