C語言注釋風格

注釋風格

一、前言

注釋是源碼程序中非常重要的一部分，一般情況下，源程序有效注釋量必須在20%以上。

注釋的原則是有助於對程序的閱讀理解，所以注釋語言必須准確、易懂、簡潔，注釋不宜太多也不能太少，注釋的內容要清楚、明了、含義准確，防止注釋二義性，該加的地方一定要加，但不必要的地方一定不要加。

注釋風格很多，這里只是對於我的代碼進行規范。

二、風格

1、文件注釋

• FileName 文件名
• Description 模塊描述
• Change Logs 變更日志

/*
 * Copyright (C), 1988-1999, Xxxxxx Tech. Co., Ltd.
 * FileName: xxx
 * Description: balabalabalabalabalabalabalabalabala
    balabalabalabalabalabalabalabalabalabalabalabala
 * Change Logs: 
    |Date           |Author       |Notes     |version
    |2010-03-22     |XXX          |XXX       |1.0.0
 */

2、函數注釋

• Function 函數名稱
• Description 函數描述
• Calls 調用的函數清單
• Input 輸入參數說明，包括每個參數的作用、取值說明及參數間關系
• Output 輸出參數的說明
• Return 函數返回值的說明
• Others 其他說明

/*
 * Function:
 * Description:
 * Calls:
 * Input:
 * Input:
 * Output:
 * Return:
 * Others:
 */

3、宏定義注釋

• @define 定義塊概述
• No error 定義值說明

/* @define xxx */
#define XXX_ERROR_OK              0   /* No error           */
#define XXX_ERROR_INVALID_TOKEN   1   /* Invalid token      */
#define XXX_ERROR_EXPECT_TYPE     2   /* Expect a type      */

4、結構體注釋

• @struct 結構體概述
• next item 結構體元素說明

/* @struct xxx */
struct xxx_syscall_item
{
    struct xxx_syscall_item* next;    /* 下一個item */
    struct xxx_syscall syscall;       /* syscall */
};

5、全局變量

全局變量要有較詳細的注釋，包括對其功能、取值范圍、哪些函數或過程存取它以及存取時注意事項等的說明。

• Description 作用描述
• Scope 作用域
• Range 取值范圍
• Notice 注意事項
• Others 其他說明

/* @variable temp */
/* Scope: 存儲溫度值 */
/* Range: -128 - 127 */
/* Notice: xxxxx */
/* Others: xxxxx */
extern char temp = 0;