代碼注釋規則

語言編寫規范之注釋 ------------------------------------------------------- 1. 注釋原則    1.1 項目開發中，盡量保持代碼注釋規范和統一。    1.2 注釋方便了代碼的閱讀和維護。    1.3 邊寫代碼邊注釋，修改代碼時要相應修改注釋，保證注釋和代碼的一致性。    1.4 注釋要簡潔明確，不要出現形容詞。      1.5 通過注釋可以快速知道所寫函數的功能，返回值，參數的使用。 2. 文件頭部注釋 /******************************************************************************** * @File name: biu.c * @Author: Tobiubiu * @Version: 1.1 * @Date: 2017-5-24 * @Description: The function interface。 ********************************************************************************/ 還可以增加：版權說明等。 3. 結構體、全局變量等的注釋     int num; /*全局變量的作用*/     /*結構體的功能*/     typedef struct{         int h; /*High risk*/         int l; /*Low risk*/         int m; /*Middle risk*/         int i; /*Information risk*/     }risk; 4. 函數的注釋 函數頭部應進行注釋，列出：函數的目的/功能、輸入參數、輸出參數、返回值、調用關系（函數、表）等 /******************************************************* * * Function name ：insert_hhistory * Description        : Insert to bd_host_history * Parameter         ： *        @ipsql            SQL statement *        @host_level        Risk level     *        @total            The total number of risk *        @t_id            task id *        @t_uuid            task uuid *        @ipaddr            target ipaddr     *        @end_time        task end time * Return          ：0 success  ,  other fail **********************************************************/ int insert_hhistory(char* ipsql,risk host_level,int total,int t_id,char* t_uuid,char* ipaddr,long int end_time) {     /*     *    如果程序過於復雜，這里可以寫明，具體算法和思路。     */ } 5. 建議     5.1 一般情況下，源程序有效注釋量必須在20％以上。 注釋不宜太多、不宜太少，准確易懂簡潔；     5.2 注釋格式盡量統一，建議使用“/* …… */”；     5.3 避免在一行代碼或表達式的中間插入注釋；         說明：除非必要，不應在代碼或表達中間插入注釋， 否則容易使代碼可理解性變差。     5.4 通過對函數或過程、變量、結構等正確的命名以及合理地組織代碼的結構，使代碼成為自注釋的。         說明：清晰 准確的函數、變量等的命名，可增加代碼可讀性，並減少不必要的注釋。     5.5 在代碼的功能、意圖層次上進行注釋，提供有用、額外的信息。         說 明：注釋的目的是解釋代碼的目的、功能和采用的方法，提供代碼以外的信息，幫助讀者理解代碼，防止沒必要的重復注釋信息。