我的對註釋使用的總結

我的對註釋使用的總結：（參考：http://blog.csdn.net/shiyuezhong/article/details/8205281 做者:shiyuezhong）

Key：註釋條件，註釋類別，註釋快捷鍵，註釋規範（我的經常使用）

背景：模擬操做系統的課程設計的代碼量算是我學習編程以來相對較多的，代碼量大的同時，方法間的調用十分頻繁，調用者也包括了好幾個類（這跟項目結構有關係，一開始沒有作好分析）。此以前不過重視註釋的規範，看了隊友的代碼才發現，在IDE的幫助下，若是按照規定的註釋規則，在使用到方法或者新建對象時，註釋的內容能夠在鼠標懸浮下顯示，能夠借註釋提示本身定義的某個方法或者類的使用說明，參數說明等，省去回到類或者方法找註釋的時間。固然，若是沒有按照規則寫註釋，就只能手動回去找了。在團隊合做中，若是使用不符合規範的註釋，可能會讓隊友浪費不少沒必要要的時間。

正文：

合理地運用註釋是團隊開發合做的重要細節，它能提升代碼的規範性和可讀性，並且在IDE的幫助下，使用符合規則的註釋能夠方便本身開發時就地查看部分代碼註釋，一樣的也方便了他人閱讀代碼。

代碼註釋要求註釋形式統一，內容言簡意賅，準確明瞭地表達註釋意圖。

註釋條件（參考：http://blog.csdn.net/shiyuezhong/article/details/8205281 做者:shiyuezhong）

一、基本註釋（必須加）

(a)    類（接口）的註釋

(b)    構造函數的註釋

(c)    方法的註釋（持久化對象或VO對象的getter、setter方法不需加註釋）

(d)    全局變量的註釋

(e)    字段/屬性的註釋

二、特殊必加註釋（必須加）

(a)    典型算法必須有註釋。

(b)    在代碼不明晰處必須有註釋。

(c)    在代碼修改處加上修改標識的註釋。（*合做中使用隊友代碼尤爲注意）

(d)    在循環和邏輯分支組成的代碼中加註釋。

(e)    爲他人提供的接口必須加詳細註釋。

 

註釋格式（參考：http://blog.csdn.net/shiyuezhong/article/details/8205281 做者:shiyuezhong）

1.單行(single-line)註釋：「//……」」/* ... */」

2.塊(block)註釋：「/*……*/」(塊註釋通常包含多行文本)

3.文檔註釋：「/**……*/」 （文檔註釋可在鼠標懸浮時顯示）

4. javadoc 註釋標籤語法

@author   對類的說明 標明開發該類模塊的做者

@version   對類的說明 標明該類模塊的版本

@see     對類、屬性、方法的說明 參考轉向，也就是相關主題

@param    對方法的說明 對方法中某參數的說明

@return   對方法的說明 對方法返回值的說明

@exception  對方法的說明 對方法可能拋出的異常進行說明

 

爲了能顯示文檔註釋，須要對於不一樣的情境使用特定的註釋語法，使用相應的註釋快捷鍵能提升效率。

1. 幾種註釋快捷鍵（Android Studio)

        a.單行註釋//      ctrl+/

        b.單行註釋/**/    ctrl+shift+/

        c.塊註釋          /*+回車

        d.方法註釋       /**+回車

2. 幾種註釋規範：

        a.全局變量

          /** 全局變量註釋*/

private int TOTAL;

   

         b.類（接口）註釋（新建類時會在類頭部自動生成註釋模板內容）

/**

 * 類描述

 * Created by ${USER} on ${DATE}

 */

public class Foo {

}

註釋模板設置（android studio)：File->Settings->IDE Settings->File and Code Templates -> include(Tab欄） ->選FileHeader

 

c.構造方法或普通方法的註釋(在含有參數的方法(包括構造方法)上方 輸入/**後回車會對參數進行註釋)

public class Foo {

    /**

     * 對構造方法的描述

     */

    public Foo(){

...

    }

        /**

         * 對方法的描述

     * @param a 對參數a的描述

     */

    private void test(int a){

        ...

    }

}

 

對於註釋的使用，總結以下：

1. 單行註釋用於描述普通變量（10字之內，儘可能不要換行），

        例 private String title;//不能超過120箇中文字符

    或者對某行代碼進行解釋

         %^E%^*&(*&(*)*)(T^%$%^$%   //只對邏輯不容易看懂代碼的進行註釋

2. 常量註釋用/**  常量說明  */

         例：/**  CONSTANT是常量  */

         private int CONSTANT;

3. 通常不對getter 和setter方法註釋。

4. 註釋的目的是幫助閱讀代碼。不要爲了註釋而註釋。使用合理的命名方法能夠幫助精簡註釋。