前言
今天我们开始C++的学习，本文介绍了如何编写第一个C++程序以及C++注释语法与注释编写规范。
一、第一个C++程序
/*
#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;
}
二、C++注释语法
语法
C++注释语句一般分为行注释与块注释
行注释： // 仅注释一行内容
块注释： /**/ 注释多行内容
被注释的内容不参与程序的编译，因此注释的多少不会影响程序的运行与大小。
注释编写规范
注释是程序代码中用于解释说明代码功能、实现方法等内容的文字信息。注释编写规范旨在使代码更易读懂、易维护、易重构。
下面是一些通用的注释编写规范：
- 注释应该用自然语言书写，避免使用专业术语或缩写，以便其他开发人员可以理解。
- 注释应该清晰明了地描述代码的功能和目的，而不是简单地重复代码意义。
- 注释应该放在代码之前或之后，并与代码保持一致缩进。注释也可以加在代码行内，但要避免过度使用。
- 注释应该及时更新。如果更改了代码功能或实现方式，请记得更新相应的注释。
- 在函数和方法定义上方添加文档字符串（Docstring）注释，并遵循特定的格式规范，如Google Docstring，Numpy - Docstring等。
- 对于公共接口和API，注释应该包含参数类型、返回值类型、异常处理信息等。
- 避免使用无用的注释。例如，注释掉的代码块已经足够表达了过去的想法，删除就好。
- 避免使用显而易见的注释，比如"increment i by 1"
为了使得代码更易读懂、易维护、易重构，C++注释应包含以下内容：
- 函数、类、变量的作用和意义：注释应该清晰明了地描述函数、类、变量的作用和意义，告诉其他开发人员它们的使用场景和目的。
- 参数的类型和含义：在函数或方法的参数前面添加注释，解释每个参数的类型和含义，让其他开发人员知道如何正确使用函数。
- 函数返回值的类型和含义：注释应该说明函数的返回值类型和含义，并且指出这个返回值有什么特殊含义。
- 异常信息的说明：如果函数可能会抛出异常，注释应该详细说明哪些情况下会抛出异常以及异常的类型和含义。
- 特殊的注意事项：如果代码有一些特殊的注意事项，比如代码执行顺序、线程安全性、代码效率等，注释应该进行说明。
例如：
/**
* @brief 计算两个数相加的结果
*
* 该函数用于计算两个整数相加的值，并返回结果。
*
* @param[in] a 整数a
* @param[in] b 整数b
*
* @return 两个整数相加的结果
*
* @note 该函数在进行加法操作时不考虑溢出情况
*/
int add(int a, int b) {
return a + b;
}
上述注释利用Doxygen风格的标记来描述函数的参数、返回值、注意事项等信息，使得代码更加易读、易理解。
总结
本文主要介绍了C++语言的入门、注释语法及规范，以及注释应包含的内容。
在C++语言的入门部分中，我们讲解了一个简单的“Hello World!”程序，并且对main函数进行了详细解释。
在注释语法和规范方面，我们列出了C++中常见的行注释和块注释，并且给出了注释编写规范，包括如何描述函数、类、变量的作用和意义，如何描述函数参数、返回值和异常信息等。
最后，我们提供了一个C++注释样例，进一步说明了注释如何更好地提高代码可读性和可理解性。
全篇结束，再见！