编程规范

【文章摘要】

       “没有规矩，不成方圆”，在实际的软件开发项目中，做任何事情都不是随心所欲的，我们编写代码需要遵守项目组约定的编程规范。很遗憾，在学校的计算机课程中，重在教导学生实现一定的程序功能，对程序的编写规范很少提及，这也就导致了从学校毕业踏上工作岗位之后一段艰辛的学习过程。

       本文根据自身的软件开发实践，对实际的软件开发项目中编写C语言和SQL语言程序时所需遵守的规范进行了详细的介绍，旨在让广大即将从事软件开发工作的程序员们懂得编程规范的重要性，以编写出整洁美观的代码，并从容面对未来的工作。

【关键词】

       C语言  SQL语句  编程规范  开发  流程

 

第一部分 C语言编程规范

       在通信类软件中，C语言是常用的编程语言。在编写C语言程序的过程中，我们需要遵守的编程规范包括：

       1. 程序的版式和注释

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

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

       头文件起到了一个辅助的作用，简要地反应出本程序的基本功能。头文件的内容包括：宏定义、结构体定义、函数的声明等。头文件的版式可采用以下的样式：

/***************************************************************

*版权所有 (C)2014,公司名称。

*

*文件名称：

*内容摘要：

*其它说明：

*当前版本：

*作   者：

*完成日期：

*

*修改记录1：  //修改历史记录，包括修改日期、版本号、修改人及修改内容等

*  修改日期：

*  版本号：

*  修改人：

*  修改内容：

***************************************************************/

 

#ifndef _XXX_H             // 防止头文件被重复引用

#define _XXX_H

 

/**************************************************************

相关宏定义

**************************************************************/

 

/**************************************************************

相关结构体定义

**************************************************************/

 

/**************************************************************

本程序中出现的函数的声明

**************************************************************/

#endif

 

       第二，实现文件的版式和注释。

       源文件(.c)文件是程序的核心，所有的工作都是在里面完成的。该文件里面主要是一些函数的实现。源文件可采用以下的版式来书写：

/***************************************************************

*版权所有 (C)2014,公司名称。

*

*文件名称：

*内容摘要：

*其它说明：

*当前版本：

*作       者：

*完成日期：

*

*修改记录1：   //修改历史记录，包括修改日期、版本号、修改人及修改内容等

*  修改日期：

*  版本号：

*  修改人：

*  修改内容：

*

*修改记录2：  //修改历史记录，包括修改日期、版本号、修改人及修改内容等

*  修改日期：

*  版本号：

*  修改人：

*  修改内容：

***************************************************************/

 

/**************************************************************

头文件引用

**************************************************************/

 

/**************************************************************

全局变量定义

**************************************************************/

 

/**************************************************************

函数实现

**************************************************************/

 

       函数实现是程序的核心，函数头部的可采用如下的版式：

/**********************************************************************

*功能描述：

*输入参数：

*输出参数：

*返  回  值：

*其它说明：

*修改日期                 版本号         修改人         修改内容

* ----------------------------------------------------------------------

* YYYYMMDD            XXX             Name            YYY

***********************************************************************/

 

        2. 变量及函数的命名

       本小节以下面的代码为例进行说明：

/***************************************************************

*版权所有 (C)2014,company name。

*

*文件名称：example.c

*内容摘要：用于示范如何给变量和函数做规范的命名

*其它说明：无

*当前版本：V1.0

*作       者：XXX

*完成日期：YYYYMMDD

*

*修改记录1：   //修改历史记录，包括修改日期、版本号、修改人及修改内容等

*  修改日期：

*  版本号：

*  修改人：

*  修改内容：

***************************************************************/

#include <stdio.h>

 

float ProcessFactorial(INT32iInputValue);       // 函数声明

 

/**********************************************************************

*功能描述：主函数

*输入参数：无

*输出参数：无

*返  回  值：无

*其它说明：无

*修改日期           版本号          修改人        修改内容

*--------------------------------------------------------------------

* YYYYMMDD       V1.0           XXX              创建

***********************************************************************/

int main()

{

   int  iInputValue = 0;

   float fResult    = 0.0;

 

   printf("Please input an integer number: ");

   scanf("%d", &iInputValue);

 

   fResult = ProcessFactorial(iInputValue);     // 调用求阶乘的函数

 

   printf("%d!=%10.0f\n", iInputValue, fResult);

 

    return 0;

}

 

 

/**********************************************************************

*功能描述：求一个数的阶乘

*输入参数：iInputValue-输入值

*输出参数：无

*返回值：求阶乘后的结果

*其它说明：无

*修改日期           版本号          修改人        修改内容

*--------------------------------------------------------------------

* YYYYMMDD       V1.0            XXX          创建

***********************************************************************/

float ProcessFactorial(INT32 iInputValue)

{

   float fResult    = 0.0;

 

   //先判断输入值是否小于0

   if (iInputValue < 0)

   {

       printf("iInputValue <0, dataerror!");

       return -1;

   }

   else

   {

       if (iInputValue == 0 || iInputValue == 1)  // 0和1的阶乘是1

       {

           fResult = 1;

       }

       else

       {

           fResult =ProcessFactorial(iInputValue-1)*iInputValue; //执行递归调用

       }

        

      return(fResult);

   }

}

 

       有关变量及函数的命名，说明如下：

       (1) 变量命名和函数命名应具备描述性，不要过度缩写。变量的命名应该使用名词，如fResult；函数的命名应该使用“命令性”动词，如ProcessFactorial。

       (2) 不管是函数还是变量，它们的命名只有一个原则：让读者一眼就能够看出它们表达的意思。如ProcessFactorial函数，一看到它，就大概能够明白这是在求阶乘(如果你英语确实不好，那就另当别论了)；iInputValue变量，表示输入值；fResult变量，表示结果值。我们要让代码自己来说话，而不是要作者向别人解释半天才行。

       (3) 为了让读者看到一个变量就知道其类型，在变量的最前面，通常会有一个标识类型的字母。如iInputValue中的第一个字母“i”表示这是一个整型变量(“i”代表“int”)，fResult中的第一个字母“f”表示这是一个浮点型变量(“f”代表“float”)。这样做，也是为了更进一步让读者对代码能够了然于心，能够很容易读懂，这样也省去了作者很多向别人解释的时间。

       (4) 函数的功能要单一，不要设计多用途的函数；函数体的规模要小，将函数内的代码行数控制在项目中规定的范围之内。此外，要尽量避免函数带有“记忆”功能，相同的输入应该产生相同的输出。

       (5) 始终要明白，我们第一是为人编写代码，其次才是计算机。如果只是计算机能够读懂的代码，不是好代码，也无法体现出一个编程人员的水平。

 

        3. 有关C语言的其它编程规范

        编写出整洁美观的代码是对一个开发人员的基本要求，有关C语言的其它编程规范及相关内容，请阅读本人CSDN博客专栏《软件项目实践中的C语言一瞥》：http://blog.csdn.net/column/details/anotherc.html。

 

 

第二部分 SQL语言编程规范

       通信类软件中，常常需要处理大量的用户信息，这就需要与数据库打交道。在编写SQL语言程序的过程中，我们需要遵守的编程规范包括(为了方便说明，本部分的所有代码均是基于Sybase数据库实现)：

       1. SQL文件的布局

       SQL脚本代码布局示例如下：

--*********************************************************************

--版权所有 (C)2014, Companyname。

--数据库版本： Sybase ASEEnterprise 15.0

--内容摘要：脚本文件布局示例

--作        者： XXX

--完成日期： YYYYMMDD

--修改记录1：

--    修改日期：

--    版本号：

--    修改人：

--    修改内容：

--**********************************************************************/

 

--**************************************************

-- initialization 初始化            

--**************************************************

use master

go

use xxx              -- 要使用的数据库

go

checkpoint

go

 

dump tran xxx with no_log   -- 日志截断处理

go

 

--************************************************************

-- user and right creation用户及权限的建立     

--************************************************************

exec sp_addalias xxx, dbo

go

 

--***********************************************************************

-- table creation   数据表的创建

--***********************************************************************

--样例表tb_example

if exists(select 1 from sysobjects where id =object_id('tb_example'))

begin

    drop table tb_example

end

go

 

create table tb_example

(

    name    varchar(30)   not null,           --名字

    age       int                  not null           --年龄

)

go

 

--创建索引

create index idx_tb_example1 on tb_example(name)

go

 

--************************************************************

-- procedure creation      存储过程的创建     

--************************************************************

--信息查询存储过程pr_selectinfo

--输入参数：@v_name姓名，@v_age 年龄

--输出参数：无

if exists (select 1 from sysobjects where id =object_id('pr_selectinfo'))

begin

    drop procedurepr_selectinfo

end

go

 

create procedure pr_selectinfo

    @v_name      varchar(30),         --姓名

    @v_age        int                         --年龄

as

begin

    ......

end

go

 

print 'create procedure pr_selectinfo ok'

go

 

--**************************************************

-- task creation      数据库任务的创建

--**************************************************

……

 

--**************************************************

-- finalization    结束

--**************************************************

……

 

        2. SQL脚本的注释

        注释在SQL脚本的编写中占有非常重要的地位。优美的、得当的注释不仅有助于研发人员理解程序，还能够提高编程效率。

        (1) 文件头部的注释

--*********************************************************************

-- copy right (C)2014, company name.

-- DB Type: XXX

-- Content: XXX

-- Created: YYYY.MM.DD

-- Modify1: The name of the author

-- Date1: YYYY.MM.DD

-- version1: The original version of the product

-- Modify2: The name of who modified the file

-- Date2: YYYY.MM.DD

-- version2: The updated version of the product

--**********************************************************************

 

        (2)    文件摘要信息的注释

--********* XXX(Version)DataBase Table Creating*********

--*  1    table1                : description1

--*  2    table2                : description2

--*  3    table3                : description3

. . . . . .

--***************************************************

 

        (3)    表或存储过程开头处的注释

-- XXX(The name of the table or procedure, and what it is used for)

The definition of the table or procedure

 

       (4)    表的各字段之后的注释

create table tb_XXX

(

    AAA               int                                   not null,          -- description1

    BBB              varchar(256)                  not null,          -- description2

    CCC              int default(0)                        null,          -- description3

    DDD             varchar(256)  default('''')     null,           -- description4

    . . . . . .

)

 

        (5)    存储过程的注释

create procedure pr_XXX

    @AAA          varchar(30),        -- description1

    @BBB          int,                       -- description2

    . . . . . .

as

begin

declare

    @CCC         int,                          --description3

    @DDD         varchar(100),        -- description4

    . . . . . .

    . . .. . .

    -- YYY(name) add YYYYMMDD for ZZZ begin

    . . . . . .

    -- YYY(name) add YYYYMMDDfor ZZZ end

    . . . . . .

    statement1                    -- YYY add YYYYMMDDdescription5

    . . . . . .

    statement2                    -- YYY modify YYYYMMDD description6

     . . . . . .

    statement3                    -- YYY delete YYYYMMDD description7

    . . . . . .

    . . . . . .

    statement4                    -- description8(important statement)

    . . . . . .

end

 

        3. 数据库表及索引的创建

        要做到字段命名恰如其分，并在适当的字段上建立索引。样例如下：

-- tb_XXX

create table tb_XXX

(

     AAA               varchar(30)              not null,   -- AAA

     BBB               int                              not null,   -- BBB

     . . . . . .

     . . . . . .

    firstprocesstime         varchar(24)   default('') null,   -- yyyy.mm.dd hh24:mi:ss

    secondprocesstime    varchar(24)  default('') null,    -- yyyy.mm.dd hh24:mi:ss

    thirdprocesstime         varchar(24)  default('') null,   --yyyy.mm.dd hh24:mi:ss

    . . . . . .

   nextprocesstime  varchar(24) defaultconvert(varchar,getdate(),102)+' '+convert(varchar,getdate(),108)      not null,  -- yyyy.mm.dd hh24:mi:ss

. . . . . .

)

go

 

create unique index idx1_tb_XXX on tb_XXX(AAA)

create index idx2_tb_XXX on tb_XXX(BBB)

create index idx4_tb_XXX on tb_XXX(nextprocesstime)

go

  

       4. 有关SQL语言的其它编程规范

      有关SQL语言的其它编程规范包括：空行与空格、begin与end的使用，数据操纵语言(DML)的书写等，详见本人CSDN博客(http://blog.csdn.net/zhouzhaoxiong1227?viewmode=contents)有关SQL语言的内容。

 

 

       编写出规范的代码，不仅可以体现出一个软件开发人员的专业素质，还可以反映出一个人做事的态度。作为一个合格的软件开发工程师，我们一定要时刻将编程规范牢记心中，做出高质量的软件来。

       最后，附上一个典型的、规范的软件研发流程图。