软件开发(6):程序的版式和注释

第1部分 重新认识C语言

程序的版式和注释 

 

        在《高质量程序设计指南(C/C++语言)》中,作者说:可以把程序的版式比喻为“书法”,好的“书法”可以让人对程序一目了然,看得兴致勃勃。确实,我们一打开程序,首先看到的便是程序的排版,我们的第一印象便是程序写得是工整还是凌乱。都说第一印象很重要,为了给大家留下好的第一印象,我们一定要注重程序的版式。

        此外,好的注释能够帮助读者更快地理解程序,提高工作的效率。也许是因为工作比较忙的缘故,很多软件工程师不喜欢为自己的程序写注释,认为这样做是没有必要的。那么,如果给他一份毫无注释的代码,他会有什么样的感受呢?在程序中,优美的、得当的注释能够起到锦上添花的作用,更能够体现出一个工程师的专业素质。因此,写注释实在是很有必要的。

        在C语言程序中,一般都包括了头文件(.h文件)源文件(.c文件),它们的版式及注释如下:

        第一,头文件的版式和注释。

        头文件起到一个辅助的作用,简要地反应出本程序的基本功能。

        一般说来,头文件的版式可采用以下的样式:

<a target=_blank id="L1" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L1" rel="#L1" style="color: rgb(102, 102, 102); text-decoration: none;">  1</a>
<a target=_blank id="L2" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L2" rel="#L2" style="color: rgb(102, 102, 102); text-decoration: none;">  2</a>
<a target=_blank id="L3" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L3" rel="#L3" style="color: rgb(102, 102, 102); text-decoration: none;">  3</a>
<a target=_blank id="L4" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L4" rel="#L4" style="color: rgb(102, 102, 102); text-decoration: none;">  4</a>
<a target=_blank id="L5" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L5" rel="#L5" style="color: rgb(102, 102, 102); text-decoration: none;">  5</a>
<a target=_blank id="L6" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L6" rel="#L6" style="color: rgb(102, 102, 102); text-decoration: none;">  6</a>
<a target=_blank id="L7" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L7" rel="#L7" style="color: rgb(102, 102, 102); text-decoration: none;">  7</a>
<a target=_blank id="L8" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L8" rel="#L8" style="color: rgb(102, 102, 102); text-decoration: none;">  8</a>
<a target=_blank id="L9" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L9" rel="#L9" style="color: rgb(102, 102, 102); text-decoration: none;">  9</a>
<a target=_blank id="L10" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L10" rel="#L10" style="color: rgb(102, 102, 102); text-decoration: none;"> 10</a>
<a target=_blank id="L11" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L11" rel="#L11" style="color: rgb(102, 102, 102); text-decoration: none;"> 11</a>
<a target=_blank id="L12" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L12" rel="#L12" style="color: rgb(102, 102, 102); text-decoration: none;"> 12</a>
<a target=_blank id="L13" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L13" rel="#L13" style="color: rgb(102, 102, 102); text-decoration: none;"> 13</a>
<a target=_blank id="L14" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L14" rel="#L14" style="color: rgb(102, 102, 102); text-decoration: none;"> 14</a>
<a target=_blank id="L15" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L15" rel="#L15" style="color: rgb(102, 102, 102); text-decoration: none;"> 15</a>
<a target=_blank id="L16" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L16" rel="#L16" style="color: rgb(102, 102, 102); text-decoration: none;"> 16</a>
<a target=_blank id="L17" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L17" rel="#L17" style="color: rgb(102, 102, 102); text-decoration: none;"> 17</a>
<a target=_blank id="L18" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L18" rel="#L18" style="color: rgb(102, 102, 102); text-decoration: none;"> 18</a>
<a target=_blank id="L19" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L19" rel="#L19" style="color: rgb(102, 102, 102); text-decoration: none;"> 19</a>
<a target=_blank id="L20" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L20" rel="#L20" style="color: rgb(102, 102, 102); text-decoration: none;"> 20</a>
<a target=_blank id="L21" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L21" rel="#L21" style="color: rgb(102, 102, 102); text-decoration: none;"> 21</a>
<a target=_blank id="L22" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L22" rel="#L22" style="color: rgb(102, 102, 102); text-decoration: none;"> 22</a>
<a target=_blank id="L23" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L23" rel="#L23" style="color: rgb(102, 102, 102); text-decoration: none;"> 23</a>
<a target=_blank id="L24" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L24" rel="#L24" style="color: rgb(102, 102, 102); text-decoration: none;"> 24</a>
<a target=_blank id="L25" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L25" rel="#L25" style="color: rgb(102, 102, 102); text-decoration: none;"> 25</a>
<a target=_blank id="L26" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L26" rel="#L26" style="color: rgb(102, 102, 102); text-decoration: none;"> 26</a>
<a target=_blank id="L27" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L27" rel="#L27" style="color: rgb(102, 102, 102); text-decoration: none;"> 27</a>
<a target=_blank id="L28" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L28" rel="#L28" style="color: rgb(102, 102, 102); text-decoration: none;"> 28</a>
<a target=_blank id="L29" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L29" rel="#L29" style="color: rgb(102, 102, 102); text-decoration: none;"> 29</a>
<a target=_blank id="L30" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L30" rel="#L30" style="color: rgb(102, 102, 102); text-decoration: none;"> 30</a>
<a target=_blank id="L31" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L31" rel="#L31" style="color: rgb(102, 102, 102); text-decoration: none;"> 31</a>
<a target=_blank id="L32" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L32" rel="#L32" style="color: rgb(102, 102, 102); text-decoration: none;"> 32</a>
<a target=_blank id="L33" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L33" rel="#L33" style="color: rgb(102, 102, 102); text-decoration: none;"> 33</a>
            
            
            
            
/***************************************************************
*版权所有 (C)2014,公司名称。
*
*文件名称:
*内容摘要:
*其它说明:
*当前版本:
*作 者:
*完成日期:
*
*修改记录1: //修改历史记录,包括修改日期、版本号、修改人及修改内容等
* 修改日期:
* 版本号:
* 修改人:
* 修改内容:
***************************************************************/
#ifndef _XXX_H // 防止头文件被重复引用
#define _XXX_H
/**************************************************************
相关宏定义
**************************************************************/
/**************************************************************
相关结构体定义
**************************************************************/
/**************************************************************
本程序中出现的函数的声明
**************************************************************/
#endif
 来自CODE的代码片
Header.h
 

        说明:

        (1)在头文件开始的地方,一定要有注释,不能马上开始写代码。这里的注释主要是版权和版本相关的信息。为什么需要呢?因为我们已经不在学校了,我们写的每一行代码都属于公司,所以要有版权声明,这也是对一个职业人的基本要求。

       (2)红色字体所示的代码是为了防止头文件被重复引用,这在每个工程文件中都是必须的。

       (3)为了便于理解,我们会将很多诸如数字等信息用宏来代替,就像C语言课上我们用“PI”来代表圆周率的值一样。此时,就需要在头文件中对实现文件中需要用到的宏进行定义,并给出适当的注释,方便理解。

       (4)在实际的C语言程序,结构体是经常会用到的。例如,某个消息结构体包含了很多的字段,这时用一个结构体进行定义是很方便的。在头文件中,尽量包含本程序要用到的所有结构体。

       (5)在学校里,很多人都不习惯对函数进行声明。为了防止函数在没有定义之前就被引用,大家一定要在头文件中对本程序中出现的所有函数进行声明。为了便于理解,在某些重要函数后面一定要写上注释。

 

        第二,源文件的版式和注释。

        源文件(.c)文件是程序的核心,所有的工作都是在里面完成的。

        一般说来,源文件的版式可采用以下的样式:

<a target=_blank id="L1" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L1" rel="#L1" style="color: rgb(102, 102, 102); text-decoration: none;">  1</a>
<a target=_blank id="L2" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L2" rel="#L2" style="color: rgb(102, 102, 102); text-decoration: none;">  2</a>
<a target=_blank id="L3" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L3" rel="#L3" style="color: rgb(102, 102, 102); text-decoration: none;">  3</a>
<a target=_blank id="L4" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L4" rel="#L4" style="color: rgb(102, 102, 102); text-decoration: none;">  4</a>
<a target=_blank id="L5" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L5" rel="#L5" style="color: rgb(102, 102, 102); text-decoration: none;">  5</a>
<a target=_blank id="L6" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L6" rel="#L6" style="color: rgb(102, 102, 102); text-decoration: none;">  6</a>
<a target=_blank id="L7" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L7" rel="#L7" style="color: rgb(102, 102, 102); text-decoration: none;">  7</a>
<a target=_blank id="L8" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L8" rel="#L8" style="color: rgb(102, 102, 102); text-decoration: none;">  8</a>
<a target=_blank id="L9" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L9" rel="#L9" style="color: rgb(102, 102, 102); text-decoration: none;">  9</a>
<a target=_blank id="L10" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L10" rel="#L10" style="color: rgb(102, 102, 102); text-decoration: none;"> 10</a>
<a target=_blank id="L11" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L11" rel="#L11" style="color: rgb(102, 102, 102); text-decoration: none;"> 11</a>
<a target=_blank id="L12" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L12" rel="#L12" style="color: rgb(102, 102, 102); text-decoration: none;"> 12</a>
<a target=_blank id="L13" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L13" rel="#L13" style="color: rgb(102, 102, 102); text-decoration: none;"> 13</a>
<a target=_blank id="L14" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L14" rel="#L14" style="color: rgb(102, 102, 102); text-decoration: none;"> 14</a>
<a target=_blank id="L15" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L15" rel="#L15" style="color: rgb(102, 102, 102); text-decoration: none;"> 15</a>
<a target=_blank id="L16" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L16" rel="#L16" style="color: rgb(102, 102, 102); text-decoration: none;"> 16</a>
<a target=_blank id="L17" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L17" rel="#L17" style="color: rgb(102, 102, 102); text-decoration: none;"> 17</a>
<a target=_blank id="L18" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L18" rel="#L18" style="color: rgb(102, 102, 102); text-decoration: none;"> 18</a>
<a target=_blank id="L19" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L19" rel="#L19" style="color: rgb(102, 102, 102); text-decoration: none;"> 19</a>
<a target=_blank id="L20" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L20" rel="#L20" style="color: rgb(102, 102, 102); text-decoration: none;"> 20</a>
<a target=_blank id="L21" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L21" rel="#L21" style="color: rgb(102, 102, 102); text-decoration: none;"> 21</a>
<a target=_blank id="L22" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L22" rel="#L22" style="color: rgb(102, 102, 102); text-decoration: none;"> 22</a>
<a target=_blank id="L23" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L23" rel="#L23" style="color: rgb(102, 102, 102); text-decoration: none;"> 23</a>
<a target=_blank id="L24" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L24" rel="#L24" style="color: rgb(102, 102, 102); text-decoration: none;"> 24</a>
<a target=_blank id="L25" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L25" rel="#L25" style="color: rgb(102, 102, 102); text-decoration: none;"> 25</a>
<a target=_blank id="L26" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L26" rel="#L26" style="color: rgb(102, 102, 102); text-decoration: none;"> 26</a>
<a target=_blank id="L27" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L27" rel="#L27" style="color: rgb(102, 102, 102); text-decoration: none;"> 27</a>
<a target=_blank id="L28" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L28" rel="#L28" style="color: rgb(102, 102, 102); text-decoration: none;"> 28</a>
<a target=_blank id="L29" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L29" rel="#L29" style="color: rgb(102, 102, 102); text-decoration: none;"> 29</a>
<a target=_blank id="L30" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L30" rel="#L30" style="color: rgb(102, 102, 102); text-decoration: none;"> 30</a>
<a target=_blank id="L31" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L31" rel="#L31" style="color: rgb(102, 102, 102); text-decoration: none;"> 31</a>
<a target=_blank id="L32" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L32" rel="#L32" style="color: rgb(102, 102, 102); text-decoration: none;"> 32</a>
<a target=_blank id="L33" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L33" rel="#L33" style="color: rgb(102, 102, 102); text-decoration: none;"> 33</a>
<a target=_blank id="L34" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L34" rel="#L34" style="color: rgb(102, 102, 102); text-decoration: none;"> 34</a>
            
            
            
            
/***************************************************************
*版权所有 (C)2014,公司名称。
*
*文件名称:
*内容摘要:
*其它说明:
*当前版本:
*作 者:
*完成日期:
*
*修改记录1: //修改历史记录,包括修改日期、版本号、修改人及修改内容等
* 修改日期:
* 版本号:
* 修改人:
* 修改内容:
*
*修改记录2: //修改历史记录,包括修改日期、版本号、修改人及修改内容等
* 修改日期:
* 版本号:
* 修改人:
* 修改内容:
***************************************************************/
/**************************************************************
头文件引用
**************************************************************/
/**************************************************************
全局变量定义
**************************************************************/
/**************************************************************
函数实现
**************************************************************/
 来自CODE的代码片
src.c

        说明:

        (1)函数头部的版权和版本相关的信息与头文件的类似,也是必不可少的。

        (2)在源文件的函数中,会调用很多不在该文件中定义的函数,因此,需要将这些函数包括进来。怎么办呢?就要引用定义这些函数的头文件,像我们很熟悉的“#include <stdio.h>”。

        (3)当程序函数比较多时,会出现很多函数都需要引用同一个变量的情况,这就需要定义一个全局变量供它们使用。但全局变量的个数要尽量少,尽量不要定义多余的全局变量。什么原因呢?就拿人类来说,我们依靠别人越少,我们就会越自由,如果做很多事情都要别人点头,你的心里感觉如何?

        (4)函数实现是程序的核心,我们开头做了那么多的工作,都是为了实现函数服务的。那么函数到底应该怎么写?这是以后的内容。这里要说的是函数头部的注释。受到学校教育的影响,很多开发工程师不喜欢写注释,或者是写出很简单的注释,起不到注释应有的作用。根据作者的经验,函数头部的可采用如下的样式:

<a target=_blank id="L1" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L1" rel="#L1" style="color: rgb(102, 102, 102); text-decoration: none;">  1</a>
<a target=_blank id="L2" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L2" rel="#L2" style="color: rgb(102, 102, 102); text-decoration: none;">  2</a>
<a target=_blank id="L3" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L3" rel="#L3" style="color: rgb(102, 102, 102); text-decoration: none;">  3</a>
<a target=_blank id="L4" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L4" rel="#L4" style="color: rgb(102, 102, 102); text-decoration: none;">  4</a>
<a target=_blank id="L5" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L5" rel="#L5" style="color: rgb(102, 102, 102); text-decoration: none;">  5</a>
<a target=_blank id="L6" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L6" rel="#L6" style="color: rgb(102, 102, 102); text-decoration: none;">  6</a>
<a target=_blank id="L7" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L7" rel="#L7" style="color: rgb(102, 102, 102); text-decoration: none;">  7</a>
<a target=_blank id="L8" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L8" rel="#L8" style="color: rgb(102, 102, 102); text-decoration: none;">  8</a>
<a target=_blank id="L9" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L9" rel="#L9" style="color: rgb(102, 102, 102); text-decoration: none;">  9</a>
<a target=_blank id="L10" href="http://blog.csdn.net/zhouzhaoxiong1227/article/details/21859119#L10" rel="#L10" style="color: rgb(102, 102, 102); text-decoration: none;"> 10</a>
            
            
            
            
/**********************************************************************
*功能描述:
*输入参数:
*输出参数:
*返回值:
*其它说明:
*修改日期 版本号 修改人 修改内容
* --------------------------------------------------------------------
* YYYYMMDD XXX Name YYY
***********************************************************************/
 来自CODE的代码片
funcheader.c

        在写好注释之后,便可以开始写正式的函数实现语句了。

     

        在程序代码中,如果善用空格和空行,可使程序的版式更加的优美。有关空格和空行的使用建议如下:

        (1)  空格的使用

        1)     C语言的关键字(ifforwhileswitch)之后要留有空格,以突出该关键字;在函数名之后不要留空格,紧跟左括号‘(’,以与关键字作区别;但在函数定义的参数之间,要留有空格,如Function(x, y, z)

        2)     赋值操作符、算术操作符、比较操作符、逻辑操作符、位域操作符等,如“=”、“+=”、“>=”、“<=”、“+”、“*”、“%”、“&&”、“||”、“<<”,“^”等二元操作符的前后应当加空格。但一元操作符如“!”、“~”、“++”、“--”、“&(地址运算符)等前后不加空格。

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

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

 

        (2)  空行的使用

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

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

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

 

            有关注释,使用建议如下:

        (1)   C语言程序中,注释的书写有两种方式,一种是用“//”来标注,一种是用“/* … */”来标注。当只需要对单行代码进行注释时,可以采用第一种方式;当对多行代码进行添加或删除时,可以采用第二种方式。当然,这只是作者个人的看法,不同的项目组有不同的规范。

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

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

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

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

 

       “千里之行,始于足下”,当我们看到排版工整、注释规范的代码时,会产生继续读下去的想法(如果当时你的心情非常不好,那就另当别论了),这也就无形中提高了办事的效率。同时,会让他人对程序的作者产生好的第一印象,进而使得下一步的愉快合作成为可能。因此,注意程序的版式和注释的书写是十分重要的。

你可能感兴趣的:(软件开发,程序的版本,程序的注释)