關於程序註解(註釋)與流程圖繪製

以下是對於程序註解的整理,當然最好對工程的運行進行流程圖的繪製,記錄整體工程的運行框架,這樣在以後的使用中,重新拾起來會方便很多。

一般流程圖繪製:

註釋格式儘量統一,建議使用“/* …… */”。

  • 文件頭部進行註釋

示例:下面這段頭文件的頭註釋比較標準,當然,並不侷限於此格式,但上述信息建議要包含在內。

/*****************************************************************************
Copyright: 1988-1999, Huawei Tech. Co., Ltd.
File name: 文件名
Description: 用於詳細說明此程序文件完成的主要功能,與其他模塊或函數的接口,輸出值、取值範圍、含義及參數間的控制、順序、獨立或依賴等關係
Author: 作者
Version: 版本
Date: 完成日期
History: 修改歷史記錄列表, 每條修改記錄應包括修改日期、修改者及修改內容簡述。
*****************************************************************************/

  • 函數頭部應進行註釋

示例:下面這段函數的註釋比較標準,當然,並不侷限於此格式,但上述信息建議要包含在內。
/*************************************************
Function: // 函數名稱
Description: // 函數功能、性能等的描述
Calls: // 被本函數調用的函數清單
Called By: // 調用本函數的函數清單
Input: // 輸入參數說明,包括每個參數的作用、取值說明及參數間關係。
Output: // 對輸出參數的說明。
Return: // 函數返回值的說明
Others: // 其它說明
*************************************************/

  • 全局變量的註解

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

示例:
/* The ErrorCode when SCCP translate */
/* Global Title failure, as follows */ // 變量作用、含義
/* 0 - SUCCESS 1 - GT Table error */
/* 2 - GT error Others - no use */ // 變量取值範圍
/* only function SCCPTranslate() in */
/* this modual can modify it, and other */
/* module can visit it through call */
/* the function GetGTTransErrorCode() */ // 使用方法
BYTE g_GTTranErrorCode;

  • 程序塊的結束加註解

在程序塊的結束行右方加註釋標記,以表明某程序塊的結束。

說明:當代碼段較長,特別是多重嵌套時,這樣做可以使代碼更清晰,更便於閱讀。示例:參見如下例子。
if (...)
{
// program code
while (index < MAX_INDEX)
{
// program code
} /* end of while (index < MAX_INDEX) */ // 指明該條while 語句結束
} /* end of if (...)*/ // 指明是哪條if 語句結束

  • 關於多人合作註釋

同一個文件的代碼可能被多個人修改,這個時候需要標識出誰改動了哪些部分。

格式// add begin by 作者名 ,一個分號;,再加上原因 Reason

代碼添加的最後加上://add end

Example

// add begin by hao1-007 ; Init post's id 
var postId = 1;
//end add

或者

// add begin by liuxing 
/**
 * 多行註釋來說明原因
 */
var postId = 1;
//end add

參考網站:http://c.biancheng.net/cpp/html/761.html

https://www.jianshu.com/p/822aa0077595

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章