第五章、注释

第五章、注释

示例:注释不能消除代码的坏味道
/*判断m是否为素数*/
/*返冋值::是素数，:不是素数*/
int p(int m)
{
int k = sqrt(m):
for (int i = 2; i <= k; i++)
if (m % i == 0)
break; /*发现整除，表示m不为累数，结朿遍历*/
if (i > k)
return 1;
else
return 0;/*遍历中没有发现整除的情况，返冋*/
}
//重构代码后，不需要注释:
int IsPrimeNumber(int num)
{
int sqrt_of_num = sqrt (num);
for (int i = 2; i <= sqrt_of_num; i++)
{
if(num % i == 0)
return FALSE;
}
return TRUE;
}

原则5. 2 注释的内容要清楚、明了，含义准确，防止注释二义性。
说明:有歧义的注释反而会导致维护者更难看懂代码，正如带两块表反而不知道准确时间。

原则5. 3 在代码的功能、意图层次上进行注释，即注释解释代码难以直接表达的意图，而不是重复描述代码。
说明:注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助读者理解代码， 防止没必要的重复注释信息。对于实现代码中巧妙的、晦涩的、有趣的、重要的地方加以注释。
注释不是为了名词解释(what),而是说明用途(why)。

//示例:如下注释纯域多余。
++i; /* increment i */
if (receive_flag) /* if receive flag is TRIE */
如下这种无价值的注释不应出现(空洞的笑话，无关紧要的注释)
/*时间打限，现在是:04,根木来不及想为什么，也没人能帮我说清楚*/

规则5.1 修改代码时，维护代码周边的所有注释，以保证注释与代码的一致性。不再有用的注释要删除。
说明:不要将无用的代码所在注释中，随时可以从源代码配置库中找冋代码;即使只是想暂时排除代码，也要留个标注，不然可能会忘记处理它。

规则5. 2 文件头部必须进行注释，包括:.h 文件、.c 文件、.cpp 文件、.inc 文件、.def 文件、编译说明文件.cfg 等
说明:注释必须列出:版权信息、文件标识、内容摘要、版本号、作者、完成日期、修改信息等。

下面这段头文件注释比较标准，可不局限于此格式，但上述信息建议要包含:
/*********************************************************************
* 版权所有 (C)2013, ******公司*
* 内容摘要: // 简要描述本文件中的主要模块、函数及其功能的说明
* 当前版本: // 例: V 1.0.0
* 作 者: // 某甲
* 完成日期: // 例:2013年11月1日
* 修改记录1:// 修改历史记录，包括修改日期、修改者及修改内容 修改日期:
* 修改日期:
* 版本号:
* 修改人:
* 修改内容:
*修改记录2:
***********************************************************************/

规则5.3 函数声明处注释描述函数功能、性能及用法，包括输入和输出参数、函数返回值、可重入的要求等;定义处详细描述函数功能和实现要点，如实现的简要步骤、实现的理由、设计约束等。
说明:重要的、复杂的函数，提供外部使用的接口函数应编写详细的注释。

下面这段函数的注释比较标准，可不局限于此格式，但上述信息建议要包含:
/**********************************************************************
* 功能描述: // 函数功能描述
* 输入参数: // 输入参数说明，包括每个参数的作用、取值说明及参数间关系
* 输出参数: // 对输出参数的说明。
* 返 回 值: // 函数返回值的说明
* 修改日期
版本号
修改人
修改内容
* -----------------------------------------------
* 2013/11/01
V1.0.0
XXXX
XXXX ***********************************************************************/

规则5. 4 全局变量要有较详细的注释，包括对其功能、取值范围以及存取时注意事项等的说明。
说明:全局变量关系到程序的结构框架，对于全局变量的理解往往关系到对整个程序的正确理解，所以必须有详尽的说明。

正例 1:
/* The ErrorCode when SCCP translate */
/* Global Title failure, as follows */
/* 0 -SUCCESS 1 -GT Table error */
/* 2 —GT error Others —no use */
/* only function SCCPTranslateO in */
/* this modua1 can modify it, and other */
/* modu1e can visit it through call */
/* 变量作用、含义*/
/* 变量取值范围*/
/* the function GetGTTransErrorCode() */
/* 使用方法*/
BYTE g_GTTranErrorCode;

正例 2:
// 变量作用:错误状态码
// 变量范围:0 - SUCCESS 1 - ERROR
// 访问说明:GetErrorCode(void);
// SetErrorCode(U32 ulError)
U32 g_ulErrorCode; // 全局错误码

规则5. 5 注释应放在其代码上方相邻位置或右方，不可放在下面。如放于上方则需与其上面的代码用空行隔开，且与下方代码缩进相同。

示例:
/* active statistic task number */
#define MAX_ACT_TASK_NUMBER 1000
#define MAX ACT TASK NUMBER 1000 /* active statistic task number */
//可按如下形式说明枚举/数据/联合结构。
/* seep interface with seep user primitive message name */
enum SCCP_USER PRIMITIVE {
N_UNITDATA_1ND, /* scop notify seep user unit data come */
N_NOTICE_IND, /* seep notify user the No. 7 network can not transmission
this message */ N_UN丄丁DATA_REQ, /* seep user’s unit data transmission request*/
};

规则5. 6对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释。
说明:这样比较清楚程序编写者的意图，打效防止无故遗漏break语句。

示例:
case CMD_FWD:
ProcessFwd ():
/* now jump into case CMD_A */
case CMD_A:
ProcessAO ;
break;
//对于中间无处理的连续case,已能较淸晰说明意图，不强制注释。
switch (cmd_flag)
{
case CMDA:
case CMD_B:
{
ProcessCMD ();
break:
}
}

规则5. 7 避免在注释中使用缩写，除非是业界通用或子系统内标准化的缩写。
规则5. 8 同一产品或项目组统一注释风格。
建议5.1 避免在一行代码或表达式的中间插入注释。
建议5. 2 注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用中文， 除非能用非常流利准确的英文表达。
建议5. 3 文件头、函数头、全局常量变量、类型定义的注释格式采用工具可识别的格式。
说明:采用工具可识别的注释格式，例如doxygen格式，方便工具导出注释形成帮助文档。

补充 5. 9 注释与所描述内容进行同样的缩排
说明:可使程序排版整齐，并方便注释的阅读与理解。

反例:
int DoSomething(void)
{
// 代码段1注释
{代码段1}
// 代码段2注释
{代码段2}
}
正例:
int Function(void)
{
// 代码段1注释 
{代码段1}
// 代码段2注释
{代码段2}
}

一些注释的参考：

1. 善未实现完整的代码，或者需要进一步优化的代码，应加上 // TODO …
2. 调试的代码，加上注释 // only for DEBUG
3. 需要引起关注的代码，加上注释 // NOTE …

最后

以上就是超级河马为你收集整理的第五章、注释的全部内容，希望文章能够帮你解决第五章、注释所遇到的程序开发问题。

如果觉得靠谱客网站的内容还不错，欢迎将靠谱客网站推荐给程序员好友。