第1部分 重新认识C语言
程序的版式和注释
在《高质量程序设计指南(C/C++语言)》中，作者说：可以把程序的版式比喻为“书法”，好的“书法”可以让人对程序一目了然，看得兴致勃勃。确实，我们一打开程序，首先看到的便是程序的排版，我们的第一印象便是程序写得是工整还是凌乱。都说第一印象很重要，为了给大家留下好的第一印象，我们一定要注重程序的版式。
此外，好的注释能够帮助读者更快地理解程序，提高工作的效率。也许是因为工作比较忙的缘故，很多软件工程师不喜欢为自己的程序写注释，认为这样做是没有必要的。那么，如果给他一份毫无注释的代码，他会有什么样的感受呢？在程序中，优美的、得当的注释能够起到锦上添花的作用，更能够体现出一个工程师的专业素质。因此，写注释实在是很有必要的。
在C语言程序中，一般都包括了头文件(.h文件)和实现文件(.c文件)，它们的版式及注释如下：
第一，头文件的版式和注释。
头文件起到一个辅助的作用，简要地反应出本程序的基本功能。
一般说来，头文件的版式可采用以下的样式：
/***************************************************************
*版权所有 (C)2014, 公司名称。
*
*文件名称：
*内容摘要：
*其它说明：
*当前版本：
*作 者：
*完成日期：
*
*修改记录1： //修改历史记录，包括修改日期、版本号、修改人及修改内容等
* 修改日期：
* 版本号：
* 修改人：
* 修改内容：
***************************************************************/
#ifndef _XXX_H //防止头文件被重复引用
#define _XXX_H
/**************************************************************
相关宏定义
**************************************************************/
/**************************************************************
相关结构体定义
**************************************************************/
/**************************************************************
本程序中出现的函数的声明
**************************************************************/
#endif
说明：
(1)在头文件开始的地方，一定要有注释，不能马上开始写代码。这里的注释主要是版权和版本相关的信息。为什么需要呢？因为我们已经不在学校了，我们写的每一行代码都属于公司，所以要有版权声明，这也是对一个职业人的基本要求。
(2)红色字体所示的代码是为了防止头文件被重复引用，这在每个工程文件中都是必须的。
(3)为了便于理解，我们会将很多诸如数字等信息用宏来代替，就像C语言课上我们用“PI”来代表圆周率的值一样。此时，就需要在头文件中对实现文件中需要用到的宏进行定义，并给出适当的注释，方便理解。
(4)在实际的C语言程序，结构体是经常会用到的。例如，某个消息结构体包含了很多的字段，这时用一个结构体进行定义是很方便的。在头文件中，尽量包含本程序要用到的所有结构体。
(5)在学校里，很多人都不习惯对函数进行声明。为了防止函数在没有定义之前就被引用，大家一定要在头文件中对本程序中出现的所有函数进行声明。为了便于理解，在某些重要函数后面一定要写上注释。
第二，实现文件的版式和注释。
实现文件(.c)文件是程序的核心，所有的工作都是在里面完成的。
一般说来，实现文件的版式可采用以下的样式：
/***************************************************************
*版权所有 (C)2014, 公司名称。
*
*文件名称：
*内容摘要：
*其它说明：
*当前版本：
*作 者：
*完成日期：
*
*修改记录1： //修改历史记录，包括修改日期、版本号、修改人及修改内容等
* 修改日期：
* 版本号：
* 修改人：
* 修改内容：
*
*修改记录2： //修改历史记录，包括修改日期、版本号、修改人及修改内容等
* 修改日期：
* 版本号：
* 修改人：
* 修改内容：
***************************************************************/
/**************************************************************
头文件引用
**************************************************************/
/**************************************************************
全局变量定义
**************************************************************/
/**************************************************************
函数实现
**************************************************************/
说明：
(1)函数头部的版权和版本相关的信息与头文件的类似，也是必不可少的。
(2)在实现文件的函数中，会调用很多不在该文件中定义的函数，因此，需要将这些函数包括进来。怎么办呢？就要引用定义这些函数的头文件，像我们很熟悉的“#include <stdio.h>”。
(3)当程序函数比较多时，会出现很多函数都需要引用同一个变量的情况，这就需要定义一个全局变量供它们使用。但全局变量的个数要尽量少，尽量不要定义多余的全局变量。什么原因呢？就拿人类来说，我们依靠别人越少，我们就会越自由，如果做很多事情都要别人点头，你的心里感觉如何？
(4)函数实现是程序的核心，我们开头做了那么多的工作，都是为了实现函数服务的。那么函数到底应该怎么写？这是以后的内容。这里要说的是函数头部的注释。受到学校教育的影响，很多开发工程师不喜欢写注释，或者是写出很简单的注释，起不到注释应有的作用。根据作者的经验，函数头部的可采用如下的样式：
/**********************************************************************
*功能描述：
*输入参数：
*输出参数：
*返回值：
*其它说明：
*修改日期 版本号 修改人 修改内容
* ------------------------------------------------------------------------------------------------------
* YYYYMMDD XXX Name YYY
***********************************************************************/
在写好注释之后，便可以开始写正式的函数实现语句了。
在C语言程序中，注释的书写有两种方式，一种是用“//”来标注，一种是用“/* … */”来标注。当只需要对单行代码进行注释时，可以采用第一种方式；当对多行代码进行添加或删除时，可以采用第二种方式。当然，这只是作者个人的看法，不同的项目组有不同的规范。
“千里之行，始于足下”，当我们看到排版工整、注释规范的代码时，会产生继续读下去的想法(如果当时你的心情非常不好，那就另当别论了)，这也就无形中提高了办事的效率。同时，会让他人对程序的作者产生好的第一印象，进而使得下一步的愉快合作成为可能。因此，注意程序的版式和注释的书写是十分重要的。
(欢迎访问南邮BBS：http://bbs.njupt.edu.cn/)
(欢迎访问重邮BBS：http://bbs.cqupt.edu.cn/nForum/index)
(本系列文章每周更新两篇，敬请期待！本人新浪微博：http://weibo.com/zhouzxi?topnav=1&wvr=5，微信号：245924426，欢迎关注！)
让你提前认识软件开发---学长的软件开发经验总结(6),布布扣,bubuko.com
原文：http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119