注释标记原则
1、多种注释形态
- 那么多注释形态，目的就一个，实现各类装饰效果。
1.1 没有强调内容的注释
/* 单行注释常用于注释程序主题代码*/
1.2 有强调内容的注释
/* --> 注意：需要处理错误信息 <--*/
- 如何装饰单行注释取决于程序员的个人爱好。无论使用何种特殊字符。只要他们能够吸引眼球，并能明确表示注释的起止点即可。
1.3 不包含强调内容的多行注释
/*
*可以通过此种形式编写包含多行语句的注释
*没有需要特别强调的内容，但需要用较长的句子
进行更准确的说明时，使用此类注释。
*/
- 有时也可以在中段插入特殊字符区分注释中的内容
/*
- 校验模块的输入值
- --------------------------------------
- input ： 总计，不能使用浮点数
- input2 ：合计，用于比较平均值
*/
1.4 包含强调内容的多行注释
- 编写多行注释时，如果需要特别强调包含的代码部分或注释内容的顺序，则多采用如下形态：
/*************************************/
/*！！！！！警告（warning）！！！！！*/
/*************************************/
/* 所有数据都必须经过精确校验，并通过数十次测试以确保万无一失。*/
/************************************/
- 无论采用何种方式编写，注释最主要的用途还是引起程序员的注意，不要纠结于外观，只要能最大限度地修改眼球即可。
2、区分单行注释和注释框
2.1 注释形式的分类
- 单行注释
- 非单行注释（多行注释）
2.2 使用原则
- 初级程序员会在程序起始部分采用单行注释，这种单行注释怎么可能详细说明程序或函数呢？
- 可以把单行注释应用于补充程序主体语句，但无法提供足够多的程序或函数信息。因此，需要说明程序或函数时，应该采用多行注释。
2.3 多行注释示例
- 通常，多行注释又称”注释框“或”块注释“
- 注释框相当于程序的参考文献，对于大规模项目尤为重要。实际上，程序员可以从注释框提供的信息中获得比此程序代码本身更多的线索。
/* ========================== */
/* 原程序名：func.c */
/* 可执行程序名：func.exe */
/* */
/* 目标： 调用各文件操作函数 */
/* */
/* 编写者：豆豆哥 */
/*最初编写日期：2020年12月07日*/
/* 第一次修改日期：。。。。。*/
...................
/*第二次修改日期：。。。。。*/
/* 改进函数和函数调用 */
/* ===========================*/
#include<stdio.h>
.....省略......
3、添加"变量字典编写专用注释"
3.1 说的是什么鬼？
- 每行只声明一个变量，并在变量旁添加详细注释，这种方法就可以称为”变量字典编写专用注释“，简称”字典注释“。如下：
/*
文件名：calcarea.dic
文件用途： calcarea.prj项目所用的main.c模块的字典变量 */
/* 1. main.c中的变量*/
int area;/* 面积：xxx的面积*/
int wide;/* 宽度 xxx的宽度*/
int height;/* 高度 xxx的高度*/
/* 2. calc.c中的变量*/
int block_sum;/* 区划面积和：xxx的面积*/
int total;/* 区域面积和：xxx的面积*/
static int area;/* 保存各单位土地的面积*/
- 字典注释在程序明细中占据着至关重要的位置，千万不要忘记编写。
4、向程序插入伪代码
4.1 伪代码？
- 伪代码用来表示程序的逻辑。可以用日常语言来表述伪代码，这样那些不熟悉编程语言的人也能够很轻松的理解程序逻辑。
4.2 标注伪代码
/* [该程序的伪代码] */
/* 预定义表示输入值的整数变量num1、num2
表示最大值和最小值的max、min */
/* */
/* 将接受的两个主属性输入值依次
保存到num1和num2 */
/* 如果num1大于num2 */
/* 则num1时最大值，将其保存到max */
/* num2是最小值，将其保存到min */
/* 否则 */
/* 呼唤保存的最大值和最小值 */
/* */
/* 将max输出为最大值，min输出为最小值 */
/* [伪代码结束]*/
#include <iostream>
using namespace std;
int main()
{
int num1,num2,max,min;
if (num1 > num2) {
max = num2;
min = num1;
}
else{
max = num2;
min = num1;
}
cout << "最大值：" << max << endl;
cout << "最小值：" << min << endl;
...略
return 0；
}
- 简单的程序可能体现不出来效果，对于数10行、上百行的程序，其逻辑仅用10行左右的伪代码就可以表示。
- 因此，伪代码对快速把握程序非常有效。
5、通过注释标注程序目标
5.1 什么意思？
- 伪代码可以使逻辑一目了然，但是伪代码也多啊，一眼下去并不知道程序要干嘛，这时我们需要一行注释，用来说明程序的作用。
5.2 要求
遵守六何原则编写注释
1.何时(when) 编写日期：2020年11月1日
2.何地（where） 场所 ：xxx小组
3.何人（who） 编写者 ：豆豆哥
4.何事（what） 代码性质：c语言代码 约100行
5.为何（why） 编写理由：最大值、最小值教学
6.如何（how） 编写环境：控制台
- 上面注释有些生硬，也可以用一句话来把上面穿起来，作程序目标
- 在组成程序的各函数、类的前面都应该添加足够的注释文字和伪代码。
6、程序起始部分必须添加头注释
6.1 好处
- 头注释位于程序的其实部分，用于指出程序的题目、作者、目标等。
- 头注释相当于名片，我们通过头注释可以首先对程序有整体的认知，再基于主体注释可以对其有更深入的了解。
6.2 优秀的头注释编写示例
/* 文件名：func.c */
/* 出处：www.xxxxx.cn */
/* 编写者： 软件开发3组 豆豆哥 */
/* 目标：读取用户登录信息 */
/* 提供客户服务中心所需的数据 */
/* 使用方式：依靠操作系统中的任务计划程序
/*sched.exe */
/* 每天自动运行一次 */
/* 编译该程序得到可执行文件func。exe*/
/* 必须与sched.exe位于同一目录*/
/* 所需文件：读取模式(r)下的userlog.dat*/
/*的内容并获取统计数据，之后再写模式(w)*/
/*下的useracnt.dat中记录这些统计数据。*/
.....略....
/* 限制条件：1.userlog.dat必须事先存在*/
/* 如果该文件不存在 */
/* 则需检查logcount.exe文件能否正常运行*/
/* 2.该程序必须在凌晨2点之后运行 */
/* 需要修改任务计划sched.c时 */
/* 请注意不要修改该时间 */
/* 异常处理：出现各种错误时，应在 */
/*errlog.dat中写入错误日志文件，并立即*/
/*终止该程序 */
/* 历史记录：1.2020年12月1日 开始编写*/
/* 2. 2020年12月6日 修改程序*/
- 上面注释包含8项内容，也是必须有的
- 文件名
- 编写者
- 目标
- 使用方式
- 所需文件
- 限制条件
- 异常处理
- 历史记录
- 有人会觉着编写头注释太麻烦了。请大家不要偷懒，一定要站在其他可能修改程序的人的立场考虑问题，做出尽可能详细的说明。
7、在等于运算符旁边添加注释
对于新手程序员来说，==和=傻傻用不清，经常混淆
- 你看下面这个。count赋值错误，if语句比较也错误
while (count == 1; count++; count <= 100) {
... }
if (isThis = True) {
... }
- 我建议在旁边添加注释，这样报错的时候，容易看自己的代码意思，容易比较
7.1 不想添加怎么办？
- 也不可不添加，但是需要花费一些心思。就是在比较的时候，把常量放在等号的左边，这样检查代码的时候，就能很快地推断出这里使用的是比较运算符了
if (1 = isThis) {
... }
8. 在大括号闭合处添加注释
嵌套的大括号比较多的时候，一眼下去都不知道哪个是哪个函数，相当晕啊。
- 我觉得在代码块其实部分没有必要添加注释，没多大必要。
- 在大括号闭合处添加注释很不错，而且按照惯例，应该以end if、end main、end while、end class Myclass这种以end开头的注释
- 当然，你用语句说明闭合大括号的含义也ok
int main () {
...
if () {
...
if () {
...
} //end if
}//end if
}//end main
9、在函数内部添加详细介绍函数的注释
- 对于一般情况下已经拥有足够多的说明文档并被广泛应用的函数，没必要非得添加注释
- 但在其他情况下，无论是只在一个项目还是iyig公司内使用的函数，都应该留下详细注释
- 特别需要注意，应该严格记录如下内容：
- 函数的目标
- 个参数允许的数据类型及含义
- 返回值应用于何处
10、小结
- 遵循如下几个大方针，即使没有准则规定具体哪里添加注释哪里不要添加，也能够在一定程度上保持添加注释的习惯
- 代码本身足以说明问题时，不必添加注释。
- 代码本身不足以说明问题时，尽可能添加详细注释。