foreword

Today we start learning C++. This article introduces how to write the first C++ program and C++ comment syntax and comment writing specifications .

1. The first C++ program

/*
#include <文件名> 或 #include "文件名"
其中：<文件名> 表示在默认文件夹中寻找文件
     "文件名" 表示先在当前文件夹中寻找文件，找不到再到默认文件夹中去寻找文件
作用：引用指定文件内的内容。
例如：#include <iostream> 表示引入系统默认的输入输出流iostream
*/
#include <iostream>

/* 
使用命名空间std
如果不使用命名空间std，下方cout输出要写成 std::cout，endl要写成 std::endl;
*/
using namespace std;

/* 
main()函数是c++程序的入口
一个c++程序有且仅有一个main()函数
main 前面的int表面返回值的类型
在较新的c++标准中，主函数返回值的类型都必须为int
即主函数必须写为
int main(){
    return 0;
}
的形式
由于部分编辑器会自动补写return 0，
因此在写代码的过程中，return 0不是必须要写，
但建议是最好要写。

在较老的c++标准中，主函数的类型为void，
即 
    void main(){
    
    }
不需要返回值。
*/
int main(){
    
    
// {} 包裹的代码块表示是main函数的内容；

    // cout 表示输出到输出设备中
    // "" 双引号表示是字符串
    // endl 表示换行，同时清空输出缓存
    // ; 分号表示语句结束
    cout << "Hello World!" << endl;

    // return 将其后的值，作为函数的返回值返回。
    return 0;
}

Two, C++ comment syntax

grammar

C++ comment statements are generally divided into line comments and block comments

Line comment: // Only comment one line

Block comment: /**/ comments on multiple lines

The commented content does not participate in the compilation of the program, so the number of comments will not affect the operation and size of the program.

Comment writing specification

Comments are text information used to explain code functions, implementation methods, etc. in program codes. Comment writing conventions aim to make code easier to understand, maintain, and refactor.

Here are some general annotation writing conventions :

Comments should be written in natural language, avoiding jargon or abbreviations, so that other developers can understand them.
Comments should clearly describe the function and purpose of the code, rather than simply repeating the meaning of the code.
Comments should be placed before or after the code and indented consistently with the code. Comments can also be added inline, but avoid overuse.
Notes should be updated in a timely manner. If you change the code functionality or implementation, please remember to update the corresponding comments.
Add documentation string (Docstring) comments above function and method definitions, and follow specific format specifications, such as Google Docstring, Numpy - Docstring, etc.
For public interfaces and APIs, annotations should contain parameter types, return value types, exception handling information, etc.
Avoid useless comments. For example, a commented out block of code is enough to express an idea in the past, just delete it.
Avoid obvious comments like "increment i by 1"

In order to make the code easier to understand, maintain, and refactor, C++ comments should include the following :

The role and meaning of functions, classes, and variables: Comments should clearly describe the role and meaning of functions, classes, and variables, and tell other developers their usage scenarios and purposes.
Types and meanings of parameters: add comments before the parameters of a function or method, explaining the type and meaning of each parameter, so that other developers know how to use the function correctly.
The type and meaning of the return value of the function: the comment should explain the type and meaning of the return value of the function, and point out what special meaning this return value has.
Explanation of exception information: If the function may throw an exception, the comment should detail the circumstances under which the exception will be thrown and the type and meaning of the exception.
Special considerations: If the code has some special considerations, such as code execution order, thread safety, code efficiency, etc., comments should explain it.

For example :

/**
 * @brief 计算两个数相加的结果
 *
 * 该函数用于计算两个整数相加的值，并返回结果。
 *
 * @param[in] a 整数a
 * @param[in] b 整数b
 *
 * @return 两个整数相加的结果
 *
 * @note 该函数在进行加法操作时不考虑溢出情况
 */
int add(int a, int b) {
    
    
    return a + b;
}

The above comments use Doxygen-style tags to describe the parameters, return values, precautions and other information of the function, making the code more readable and understandable.

Summarize

This article mainly introduces the introduction of C++ language, the syntax and specification of comments, and the content that comments should contain.
In the introductory part of the C++ language, we explained a simple "Hello World!" program and explained the main function in detail.
In terms of comment syntax and norms, we list the common line comments and block comments in C++, and give the comment writing norms, including how to describe the functions and meanings of functions, classes and variables, how to describe function parameters, return values and exception information, etc.
Finally, we provide a sample C++ comment that further illustrates how comments can better improve code readability and comprehensibility.

The whole article is over, goodbye!

[C++] The first C++ program and comment syntax

Article directory