嵌入式代碼的注釋問題

簡介：

對于代碼的規(guī)范性不管是做純軟件開發(fā)的還是做嵌入式開發(fā)的或者使用各種語言的，都是非常重要的。代碼的規(guī)范性對編寫人員對代碼后期的維護以及其他開發(fā)人員閱讀等都是非常友好的。接下來我們會對代碼的規(guī)范性進行說明（當然，根據(jù)個人的情況和企業(yè)的不同可能要求不一樣，我就根據(jù)我個人的一個情況進行一些說明，本專題不作為最終范本，僅用來作為參考）

注釋問題

本篇就說說代碼的注釋問題，這東西就像去飯店吃飯一樣，有菜單、指示牌等。注釋就相當于這些，是對代碼的一種說明。

頭部注釋

說明性文件（例如.h）

注釋要列出下列幾項：版權說明、版本號、生成日期、作者、內(nèi)容、 功能、與其它文件的關系、修改日志等，頭文件的注釋中以及函數(shù)功能簡要說明。

例如：

1/*****************************************************************************
 2Copyright (c) 2016  XXXXXXXXXXXXXXXXX., Ltd. All rights reserved.
 3
 4File name:/*文件名*/
 5Date      Author:       Version: /*作者、版本及完成日期*/
 6
 7Description:/*用于詳細說明此程序文件完成的主要功能，
 8                與其他模塊或函數(shù)的接口，輸出值、取值范圍、含義及參數(shù)間的控制、順序、獨立或依賴等關系*/
 9
10Others:/*其它內(nèi)容的說明*/
11
12Function List:/*主要函數(shù)列表，每條記錄應包括函數(shù)名及功能簡要說明*/
131.…
14History:
15/*修改歷史記錄列表，每條修改記錄應包括修改日期、修改者及修改內(nèi)容簡述*/
16
171. Date:
18Author:
19Modification:
202.…
21
22*****************************************************************************/

源文件頭部注釋

源文件頭部注釋要有版本說明、版本號等

版權說明、版本號、 生成日期、作者、模塊目的/功能、主要函數(shù)、修改日志、修改人、修改日期等。

1/***********************************************************************
 2*   Copyright (C) company name  xxxCo., Ltd.                *
 3*                            All Rights Reserved.                      *
 4*   Department :                                          *
 5*   AUTHOR     : NSF                                                 *
 6************************************************************************
 7* Object        :
 8* Module        :
 9* Instance      :
10* Description   :/*模塊描述*/
11*-----------------------------------------------------------------------
12* Version:
13* Date:
14* Author:  /*作者*/
15***********************************************************************/
16/*-History--------------------------------------------------------------
17* Version       Date         Name    Changes and comments
18*=====================================================================*/

函數(shù)頭部注釋

列出函數(shù)的作用、目的、輸入輸出參數(shù)等

1/************************************************* 
2Function: /* 函數(shù)名稱*/
3Description: /* 函數(shù)功能、性能等的描述*/
4Input: /* 輸入?yún)?shù)說明，包括每個參數(shù)的作用、取值說明及參數(shù)間關系。*/ 
5Output: /* 對輸出參數(shù)的說明。*/
6Return: /* 函數(shù)返回值的說明*/
7Others: /* 其它說明，應標明是否是可重入函數(shù)*/
8*************************************************/

在寫代碼的同時，我們盡量編寫代碼編注釋，同時修改代碼也要有相對應的注釋，目的是為了注釋和代碼的一致性（想想你把項目寫完了再去注釋，你還知道哪跟哪不？）

要對所有的變量、常量其命名不能夠充分解釋其代表的意義，要進行說明。

比如：

1/* active statistic task number */
2#define ACT_TASK_NUMBER 1000
3
4#define ACT_TASK_NUMBER 1000 /* active statistic task number */

數(shù)據(jù)結構聲明(包括數(shù)組、結構、類、枚舉等)，如果其命名不是充分自注釋的，必須加以注釋。對數(shù)據(jù)結構的注釋應放在其上方相鄰位置，不可放在下面；對結構中的每個域的注釋放在此域的右方。

對于switch語句下的case語句，如果因為特殊情況需要處理完一個case后進入下一個case處理，必須在該case語句處理完、下一個case語句前加上明確的注釋。

統(tǒng)一保存為UTF-8代碼編碼格式（這個任何編譯器都有的，但是對于GB并不是所有的都支持） 。

在代碼的功能、意圖層次上進行注釋，提供有用、額外的信息。