Coding Standards Development Series-Annotated Essentials

1. Multiple annotation forms

• With so many annotation forms, one purpose is to achieve various decorative effects.

1.1 Notes without emphasis

/* 单行注释常用于注释程序主题代码*/

1.2 Notes with emphasis

/* --> 注意：需要处理错误信息  <--*/

• How to decorate single-line comments depends on the programmer's personal preference. No matter what special characters are used. As long as they are eye-catching and can clearly indicate the starting and ending points of the annotation.

1.3 Multi-line comments without emphasis

/*
*可以通过此种形式编写包含多行语句的注释
*没有需要特别强调的内容，但需要用较长的句子
进行更准确的说明时，使用此类注释。
*/

• Sometimes you can also insert special characters in the middle to distinguish the content in the comment

/*
 - 校验模块的输入值
 - --------------------------------------
 - input ： 总计，不能使用浮点数
 - input2 ：合计，用于比较平均值
*/

1.4 Multi-line comments with emphasis

• When writing a multi-line comment, if you need to emphasize the included code part or the order of the comment content, use the following form:

/*************************************/
/*！！！！！警告（warning）！！！！！*/
/*************************************/
/* 所有数据都必须经过精确校验，并通过数十次测试以确保万无一失。*/
/************************************/

• No matter what method is used for writing, the main purpose of comments is to attract the attention of programmers. Don't worry about the appearance, as long as you can modify the eyeball to the maximum extent.

2. Distinguish between single-line comments and comment boxes

2.1 Classification of annotation forms

• Single line comment
• Non-single-line comments (multi-line comments)

2.2 Principles of Use

• Junior programmers will use single-line comments at the beginning of the program . How can such single-line comments specify the program or function in detail?
• Single-line comments can be applied to supplementary program body statements, but they cannot provide enough program or function information. Therefore, when a program or function needs to be explained, a multi-line comment should be used.

2.3 Example of multi-line comments

• Usually, multi-line comments are also called "comment boxes" or "block comments"
• The comment box is equivalent to the reference of the program, which is especially important for large-scale projects. In fact, the programmer can get more clues from the information provided by the comment box than the program code itself.

/* ========================== */
/* 原程序名：func.c           */
/* 可执行程序名：func.exe     */
/*                            */
/* 目标： 调用各文件操作函数  */
/*                            */
/* 编写者：豆豆哥             */
/*最初编写日期：2020年12月07日*/
/* 第一次修改日期：。。。。。*/
...................
/*第二次修改日期：。。。。。*/
/* 改进函数和函数调用        */
/* ===========================*/
#include<stdio.h>
.....省略......

3. Add "special comment for writing variable dictionary"

3.1 What the hell are you talking about?

• Declare only one variable per line, and add detailed comments next to the variable. This method can be called "variable dictionary writing special comment", or "dictionary comment" for short. as follows:

/*
文件名：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;/* 保存各单位土地的面积*/

• Dictionary comments occupies a vital position in the program details, do not forget to write.

4. Insert pseudo code into the program

4.1 Pseudo code?

• Pseudo code is used to express the logic of the program. Pseudo-code can be expressed in everyday language, so that those who are not familiar with programming languages ​​can easily understand the program logic.

4.2 Annotate pseudo code

/* [该程序的伪代码]					*/
/*  预定义表示输入值的整数变量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；
}

• A simple program may not be effective. For a program with 10 lines or hundreds of lines, its logic can be represented by only about 10 lines of pseudo-code.
• Therefore, pseudo-code is very effective for quickly grasping the program.

5. Annotate program goals through annotations

5.1 What does it mean?

• Pseudo-code can make the logic clear at a glance, but there are so many pseudo-codes. I don’t know what the program is doing at a glance. At this time, we need a line of comments to illustrate the role of the program.

5.2 Requirements

Comply with the six-ho principle to write notes

1.何时(when)      编写日期：2020年11月1日
2.何地（where）	  场所	  ：xxx小组
3.何人（who）	  编写者  ：豆豆哥
4.何事（what）	  代码性质：c语言代码 约100行
5.为何（why）	  编写理由：最大值、最小值教学
6.如何（how）	 编写环境：控制台

• The comments above are a bit blunt, you can also use one sentence to put it on as the program target
• Sufficient comment text and pseudo-code should be added in front of the functions and classes that make up the program.

6. Header comments must be added to the beginning of the program

6.1 Benefits

• The header comment is located in the actual part of the program and is used to point out the title, author, goal, etc. of the program.
• Head comments are equivalent to business cards. Through head comments, we can first have an overall understanding of the program, and then we can have a deeper understanding of it based on the main comments.

6.2 Examples of excellent header annotation writing

/* 文件名：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日 修改程序*/

• The above comment contains 8 items, which are also required

1. file name
2. Writer
3. aims
4. How to use
5. needed file
6. limitation factor
7. Exception handling
8. history record

• Some people find it too troublesome to write header comments. Please don't be lazy, be sure to consider the problem from the standpoint of other people who may modify the program, and give as much detail as possible.

7. Add a comment next to the equal operator

For novice programmers, == and = are silly and unclear and often confused

• Look at the following. Count assignment error, if statement comparison is also wrong

while (count == 1; count++; count <= 100) {
    
     ... } 
if (isThis = True) {
    
     ... }

• I suggest adding a comment next to it, so that when you report an error, you can easily see the meaning of your code and make comparisons easier

7.1 What should I do if I don't want to add it?

• It is not necessary to add it, but it takes some thought. When comparing, put the constant on the left side of the equal sign, so that when you check the code, you can quickly infer that the comparison operator is used here.

if (1 = isThis) {
    
     ... }  

8. Add a comment at the closing of the brace

When there are many nested braces, I don't know which function is which at a glance, which is quite dizzy.

• I don't think it is necessary to add comments in the actual part of the code block, not much.
• It is good to add comments at the place where the braces are closed, and in accordance with the convention, the comments that start with end should be end if, end main, end while, end class Myclass
• Of course, you can use the statement to explain the meaning of the closing brace.

int main () {
    
    
	...
	if () {
    
    
		...
		if () {
    
    
			...
		} //end if
	}//end if
}//end main

9. Add a comment describing the function in detail inside the function

• For functions that have enough documentation and are widely used in general, there is no need to add comments
• But in other cases, whether it is only used in a project or a function used within iyig, a detailed comment should be left
• Special attention should be paid to strictly record the following content:

1. The goal of the function
2. Allowable data types and meanings of each parameter
3. Where to apply the return value

10. Summary

• Follow the following general guidelines, even if there are no guidelines specifying where to add comments and not to add, you can still maintain the habit of adding comments to a certain extent

1. When the code itself is sufficient to explain the problem, it is not necessary to add a comment.
2. When the code itself is not enough to explain the problem, add detailed comments as much as possible.