目录

前言

一、排版

二、注释

三、标识符命名

总结

---

前言

学校教会了我们如何编写代码，但是却没有教会我们如何规范的书写代码。在程序编写中，有一个好的代码编写规范是很重要的，规范的代码可以减少BUG、可读性强和后期的维护。下面介绍编写规范的代码的注意事项。

一、排版

1、程序块尽量采用缩进风格编写，缩进的空格数推荐4个。

      说明:不同的开发工具自动生成的代码可以不一致。

2、相对独立的程序块之间、变量说明之后必须加空行。

示例： 如下例子不符合规范

if (!valid_ni(ni))
{
... // program code
}
repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;

因书写如下

if (!valid_ni(ni))
{
... // program code
}


repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;

3、较长的语句（>80字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，
操作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。

perm_count_msg.head.len = NO7_TO_STAT_PERM_COUNT_LEN
+ STAT_SIZE_PER_FRAM * sizeof( _UL );

act_task_table[frame_id * STAT_TASK_CHECK_NUMBER + index].occupied
= stat_poi[index].occupied;

act_task_table[taskno].duration_true_or_false
= SYS_get_sccp_statistic_state( stat_item );

4、循环、判断等语句中若有较长的表达式或语句，则要进行适应的划分，长表达式要在低
优先级操作符处划分新行，操作符放在新行之首。 

if ((taskno < max_act_task_number)
   && (n7stat_stat_item_valid (stat_item)))
{
... // program code
}

for (i = 0, j = 0; (i < BufferKeyword[word_index].word_length)
                && (j < NewKeyword.word_length); i++, j++)
{
... // program code
}

for (i = 0, j = 0;
    (i < first_word_length) && (j < second_word_length);
     i++, j++)
{
... // program code
}

5、若函数或过程中的参数较长，则要进行适当的划分 

n7stat_str_compare((BYTE *) & stat_object,
              (BYTE *) & (act_task_table[taskno].stat_object),
              sizeof (_STAT_OBJECT));
n7stat_flash_act_duration( stat_item, frame_id *STAT_TASK_CHECK_NUMBER
                                + index, stat_object );

6、不允许把多个短语句写在一行中，即一行只写一条语句。

如下例子不合规范

num.data = 0; num.size = 0;

因如下书写

num.data = 0;
num.size = 0;

7、 if、for、do、while、case、switch、default等语句自占一行，且if、for、
do、while等语句的执行语句部分无论多少都要加括号{}。

 如下不和规范

if (time > time_1s)  LED1_ON;

因如下书写

if （time > time_1s）
{
    LED1_ON;
}

8、对齐只使用空格键，不使用TAB键。
说明：以免用不同的编辑器阅读程序时，因 TAB 键所设置的空格数目不同而造成程序布局
不整齐，不要使用 BC 作为编辑器合版本，因为 BC 会自动将 8 个空格变为一个 TAB 键，
因此使用 BC 合入的版本大多会将缩进变乱。

9、函数或过程的开始、结构的定义及循环、判断等语句中的代码都要采用缩进风格，case
语句下的情况处理语句也要遵从语句缩进要求。

10、程序块之间要有一定的分界。 

11、一行内以八十个字符为宜，不宜太长，太长不利于阅读。

二、注释

1、一般情况下，源程序的有效注释在20%以上，不宜太多也不宜太少，注释的目的是帮助程序的阅读，注释必须遵循准确、易懂、简洁

2、说明性文件（如头文件.h文件、.inc文件、.def文件、编译说明文件.cfg等）头部应
进行注释，注释必须列出：版权说明、版本号、生成日期、作者、内容、功能、与其它文件的
关系、修改日志等，头文件的注释中还应有函数功能简要说明。

头文件注释可以参考下面，但不局限于这个

/*************************************************
Copyright (C), 1988-1999, Huawei Tech. Co., Ltd.
File name: // 文件名
Author: Version: Date: // 作者、版本及完成日期
Description: // 用于详细说明此程序文件完成的主要功能，与其他模块
             // 或函数的接口，输出值、取值范围、含义及参数间的控
             // 制、顺序、独立或依赖等关系
Others:      // 其它内容的说明
Function List: // 主要函数列表，每条记录应包括函数名及功能简要说明
1. ....
History:       // 修改历史记录列表，每条修改记录应包括修改日期、修改
               // 者及修改内容简述
1. Date:
Author:
Modification:
2. ...
*************************************************/

3、源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、
主要函数及其功能、修改日志等。

下面的源文件注释是非常标准的，可以作为参考。

/************************************************************
Copyright (C), 1988-1999, Huawei Tech. Co., Ltd.
FileName: test.cpp
Author:     Version :   Date:
Description: // 模块描述
Version: // 版本信息
Function List: // 主要函数及其功能
1. -------
History: // 历史修改记录
    <author> <time> <version > <desc>
David 96/10/12    1.0    build this moudle
***********************************************************/

4、函数头部应进行注释，列出：函数的目的/功能、输入参数、输出参数、返回值、调用
关系（函数、表）等。

/*************************************************
Function:           // 函数名称
Description:        // 函数功能、性能等的描述
Calls:              // 被本函数调用的函数清单
Called By:          // 调用本函数的函数清单
Table Accessed:     // 被访问的表（此项仅对于牵扯到数据库操作的程序）
Table Updated:      // 被修改的表（此项仅对于牵扯到数据库操作的程序）
Input:              // 输入参数说明，包括每个参数的作
                    // 用、取值说明及参数间关系。
Output:             // 对输出参数的说明。
Return:             // 函数返回值的说明
Others:             // 其它说明
*************************************************/

三、标识符命名

1、标识符的命名要清晰、明了，有明确含义，同时使用完整的单词或大家基本可以理解的
缩写，避免使人产生误解。

2、命名中使用特殊的和缩写，需要注释说明。

3、自己特有的风格要保持一致，不可来回变换。

4、禁止使用单个字符（如i,j,k,x,y等），建议使用能表示具体含义还能表示变量类型的标识符。

---

总结

规范的代码不是一两天练成的，需要我们平时敲代码时多加注意，养成良好的习惯。