C++之如何写注释

基本规则

写好注释是编写代码的好习惯，有利于未来编码中查询已经编好的代码，或者说重构一些代码。在C++中写注释有两种方式：单行注释和多行注释。

1. 单行注释：在C++中，我们可以使用两个斜杠（//）来创建单行注释。这种注释只会持续到当前行的结束。例如：

// 这是一个单行注释
int x = 5;

2. 多行注释：在C++中，我们可以使用 /*和 */来创建多行注释。这种注释可以跨越多行。例如：

/* 这是一个
   多行注释 */
int x = 5;

需要注意的是，单行注释不能嵌套在多行注释中。

例如，以下代码是错误的：

/* 这是一个多行注释，但是
// 这是一个嵌套的单行注释，这是不允许的
   这是多行注释的结束 */

以上就是C++中注释的基本规则，在编写代码中，注释不易少也不易多，清晰的代码无需注释。下面来看看大家约定俗成的写注释规则吧。请注意，不同的注释书写规范有所不同，根据自己的喜好以及团队的要求来吧。

文件注释

在文件的顶部，通常会包含一些关于文件的基本信息，如文件的作用，作者，创建日期和最后修改日期等。

/*
 * File:   main.cpp
 * Author: Your Name
 * Created on: Date
 * Description: This file includes the main function of the program.
 */

类注释

对于类的注释，应在类定义的上方解释类的功能和用途。如果类继承自其他类或者实现了特定的接口，也应该在注释中提到。

/*
 * ClassName: This class does something specific.
 * It inherits from the BaseClass and implements the Interface.
 */
class ClassName : public BaseClass, public Interface {
    // class body
};

函数注释

函数注释应在函数定义之前，描述函数的功能，参数，返回值等。如果函数有特殊的使用条件或者注意事项，也应在注释中说明。

/*
 * Function: functionName
 * Description: What the function does.
 * Input: 
 *    arg1 - description of arg1
 *    arg2 - description of arg2
 * Output:
 *    return - description of return value
 */
int functionName(int arg1, string arg2) {
    // function body
}

变量注释

对于复杂的变量或者不易理解的变量，可以在其旁边添加注释，解释其作用。

int variable; // This variable is used for something specific.

块注释

对于复杂的代码块，可以在其上方添加注释，解释其功能和工作原理。

// This block of code does something specific.
for (int i = 0; i < 10; i++) {
    // loop body

行注释

对于复杂的或者关键的代码行，可以在其行尾添加注释，解释其功能和工作原理。

int x = 5; // This is a key value used in the following calculations.

在Visual Studio中编写注释

Visual Studio支持XML文档注释，这是一种特殊的注释格式，可以用来自动生成代码文档。XML文档注释以 ///或 /**开始，可以包含一些特殊的标签，如 <summary>, <param>, <returns>等。

例如在函数上方输入 ///，可以自动生成注释的模板，按照模板填写信息：

之后我们调用这个函数，就会智能提示注释信息：