关于程序注解（注释）与流程图绘制

以下是对于程序注解的整理，当然最好对工程的运行进行流程图的绘制，记录整体工程的运行框架，这样在以后的使用中，重新拾起来会方便很多。

一般流程图绘制：

注释格式尽量统一，建议使用“/* …… */”。

• 文件头部进行注释

示例：下面这段头文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。

/*****************************************************************************
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