【阅读笔记】《C程序员 从校园到职场》第三章 程序的样式（版式和注释）

参考：https://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119

一、头文件的版式和注释

/***************************************************************
*版权所有 (C)2014,公司名称。
*
*文件名称：
*内容摘要：
*其它说明：
*当前版本：
*作   者：
*完成日期：
*
*修改记录1：  //修改历史记录，包括修改日期、版本号、修改人及修改内容等
*   修改日期：
*   版本号：
*   修改人：
*   修改内容：
***************************************************************/
 
#ifndef _XXX_H             // 防止头文件被重复引用
#define _XXX_H
 
/**************************************************************
             相关宏定义（例如：常用“PI”来代表圆周率的值）
**************************************************************/
 
/**************************************************************
             相关结构体定义（在头文件中，尽量包含本程序要用到的所有结构体）
**************************************************************/
 
/**************************************************************
             本程序中出现的函数的声明              
**************************************************************/
 
#endif

二、源文件的版式和注释

先后顺序：文件说明、头文件引用、数据类型或结构体定义、函数声明、函数实现

/***************************************************************
*版权所有 (C)2014,公司名称。
*
*文件名称：
*内容摘要：
*其它说明：
*当前版本：
*作   者：
*完成日期：
*
*修改记录1：   //修改历史记录，包括修改日期、版本号、修改人及修改内容等
*   修改日期：
*   版本号：
*   修改人：
*   修改内容：
***************************************************************/


 #include <stdio.h>
/**************************************************************
                      头文件引用（会调用很多不在该文件中定义的函数）
**************************************************************/
 
/**************************************************************
                      全局变量定义（多个函数需要引用同一个变量）
**************************************************************/
 
/**************************************************************
                      函数实现
**************************************************************/

//函数头部的可采用如下的样式：

/**********************************************************************
*功能描述：
*输入参数：
*输出参数：
*返回值：
*其它说明：
*修改日期 　　 版本号 　　 修改人　　 修改内容
* --------------------------------------------------------------------
* YYYYMMDD    XXX　　   Name 　　　　 YYY
***********************************************************************/

三、空格的使用

        1)     在C语言的关键字(像if、for、while、switch等)之后要留有空格，以突出该关键字；

  　　　   在函数名之后不要留空格，紧跟左括号‘(’，以与关键字作区别；

　　　　 但在函数定义的参数之间，要留有空格，如Function(x, y, z)。

        2)     赋值操作符、算术操作符、比较操作符、逻辑操作符、位域操作符等，如“=”、“+=”、“>=”、“<=”、“+”、“*”、“%”、“&&”、“||”、“<<”，“^”等二元操作符的前后应当加空格。

　　　　但一元操作符如“!”、“~”、“++”、“--”、“&”(地址运算符)等前后不加空格。

        3)     在一行代码的结尾之后不要留空格。

        4)     在代码中，使用空格进行缩进(一般缩进为4个空格)，不要在代码中使用制符表(即TAB键)来缩进。

 四、空行的使用

        1)     空行起着分隔程序段落的作用，适当的空行将使程序的布局更加的清晰。

        2)     在每个函数定义结束之后都要加空行(两个函数之间，建议添加两个以上的空行)。

        3)     函数体首尾不要留空行，函数体中也不要随意添加空行。在函数体中，空行多用于分隔关系不是很大的代码段。

 五、注释的使用

        (1)   在C语言程序中，注释的书写有两种方式，一种是用“//”来标注（单行），一种是用“/* … */”来标注（多行）。

        (2)  注释的位置要与被描述的代码相邻，可以放在代码的上方或右方，但不可放在其下方。

        (3)  注释应当简单、准确、易懂，防止二义性，错误的注释不但无益反而会影响对代码的阅读和理解。此外，要尽量避免在注释中使用缩写，特别是不常用的缩写，以让人产生疑惑。

        (4)  要边写代码边注释，在修改代码的同时要修改相应的注释，以保证注释与代码的一致性。此外，不再有用的注释要删除掉。

        (5)  巧妙或复杂的代码段前要添加注释，比较隐晦的地方要在代码行尾添加注释。