注释的基本使用和要求

前言

主要参考 《C语言深度剖析第二版》也结合自己的部分感受，分享出这篇博客，主要面向C/C++ 方向的一点基础素养和良好注释习惯。
所有代码均使用VS2019编译运行，经测试没有问题。

注释符号的使用规范

注释语句在程序的编译过程是 将 注释语句 这个整体统统编程一个空格来看待的，所以在编译器优化时，就会将很多编译后的空格直接忽略（去掉） 然后继续执行代码

#include <stdio.h>
#include <windows.h>
int main()
{
    int /* */ i; //正确, 在编译后背解释为 空格
    char *s = "abcdefgh //hijklmn"; //正确	作为字符串的一部分了
    //Is it a\
    valid comment? //正确  \作为连接符 ，成功链接，所以第八行也是作为注释内容
    in/* */t j; //报错	因为注释部分被解释为空格，就相当于 in t j; 会报错了
    system("pause");
    return 0;
}

同样，下面这条语句也是可以正常的编译处理 的

/*这是*/#/*一条*/define/*合法的*/ID/*预处理*/replacement/*指*/list/*令*/

其语句的含义是 使用 ID 替换在程序中出现的 replacement 和 list

在遇到如下情况时，要 ==注意使用空格或是使用 () 来帮助编译器进行识别

#include <stdio.h>
#include <windows.h>
int main()
{
    int x = 10;
    int y = 0;
    int z = 5;
    int *p = &z;
    y = x/*p;	//这里不要就这样直接写，而要加上空格，或是使用 () 才能实现 相除 的功能
    system("pause");
    return 0;
}

关于注释的基本要求

• 注释应该准确 易懂 防止有二义性，错误的注释无益且有害
• 变写代码边写注释，修改代码的同时修改相应的注释，以保障注释和代码的一致性，无用的注释要及时删除
  关键代码，关键函数，关键调用，关键逻辑 部分需要有相应 的注释
• 注释是对代码的提示，而不是 文档，程序中的注释应该 简单明了，注释太多会让人眼花缭乱
• 一目了然的语句 不加注释
• 对于全局数据（全局变量，常量定义）必须要添加注释 一般不建议定义全局变量，所以在定义全局变量后需要添加注释
• 注释可以使用中文，也可以使用英文，具体要求看公司要求
• 注释的位置应该与被描述的代码相邻，可以与 该语句在同一行，也可以在该语句 上方，但是不可以在下方，同一结构中不同域的的注释要对齐
• 当代码较长，特别是有多重嵌套时，应该在一些段落的结束处添加注释，便于阅读
• 注释的缩进要与代码的缩进保持一致
• 注释代码时 应该注意 【为何做】 而不是 【怎么做】
• 数值单位一定要注释，例如业务代码涉及长度，必须说明单位是 毫米、米 还是千米
• 对变量的范围给出注释，尤其是参数，方便进行测试
• 对一系列的数字编号给出注释，尤其是在编写底层驱动程序的时候（比如引脚编号）
• 对于函数的 入口/出口 数、条件语句、分支语句 给出注释
• 避免在一行代码或表达式的中间插入注释
• 复杂函数中，在分支语句、循环语句结束之后需要适当的注释，方便区分各个分支或循环体, 如下：

while (condition)
{
    statement1;
    if (condition)
    {
        for (condition)
        {
            statement2;
        }// end for(condition)
    }
    else
    {
        statement3;
    }
}//end if(condition)`

• 对于不需要的代码，目前更推荐保险方法是使用注释进行不处理，也可以使用代码裁剪 条件编译（预处理阶段） 实现不参与编码（不是很推荐）

如下代码 就可以实现 在 #if 0 到 #endif 之间在编译阶段就不参与 但是并不推荐这种写法

//基于条件编译,代码编译期间处理
#include <stdio.h>
#include <windows.h>
int main()
{ 
 
// 也可以使用 #ifdef DEBUG  和  #endif  来达到同样的效果：如果定义了 DEBUG，就执行代码，否则就不执行
    //同理，这里可以使用 定义 不同的模式来实现 普通版/付费版/高级般 的区别
#if 0	//如果这里是 1 就可以正常执行代码
printf("for test1\n"); //test1
printf("for test2\n"); //test2
#endif
    
system("pause");
return 0;
}

最后

感谢观赏，一起提高，慢慢变强