程序规范化编写

一、规范说明

代码规范和风格的目的是要编写出简洁明了、可维护、可测试、可靠、可移植、高效的代码。

1、简单、明了、清晰：

        简单、明了、清晰的代码，也利于后期维护。

2、精简

        尽量把函数写的精简，没用的代码和变量及时清理，功能类似或者重复的代码提炼成函数。

3、保持原有代码风格一致

        保持传下来代码风格

4、减少封装

        对其他第三方库不要进行封装，既包装换成新函数。

二、排版格式和注释

排版是为了在编写代码的时候按照“一定的规矩”来编写，主要目的是为了是代码清晰、易于阅读。注释顾名思义就为注释自己的代码，以方便他人阅读，尤其是尤其维护人员。

1、排版格式

1.1 代码缩进

        代码缩进要使用制表符，也就是 TAB 键，不要使用空格键缩进！

        常规的C语言编写TAB都是4字符。

        linux的TAB键建议是8个字符，也可以是4字符。

1.2 代码行

       1、 每一行代码长度限制在80列，大于80列分成多行编写。并且在低优先级操作符划分新行，操作符放在新行之首，划分出的新行要适当进行缩进， 一般进行一级缩进即可。

        2、不要把多个语句放到一行里面，一行只写一条语句。
        3、不要在一行里面防止多个赋值语句。
        4、if、 for、 do、 while、 case、 swich、 default 等语句单独占用一行。

1.3 括号与空格

括号  

      1、代码中用到大括号“{”和“}”的地方，应该把起始大括号“{”放到行尾，把结束大括号“}”放到行首。

        2、当只有一个单独的语句的时候就可以不必要加大括号了。

空格

        1、如果要定义指针类型，或者函数返回指针类型时，“*”应该放到靠近变量名或者函数
名的一侧，而不是类型名。

        2、二元或者三元操作符两侧都要加一个空格，例如下面所示操作符：

= + - < > * / % | & ^ <= >= == != ? :

        3、一元操作符后不要加空格，如：

& * + - ~ ! sizeof typeof alignof __attribute__ defined

        4、注释符“/*”和“*/”与注释内容之间要添加一个空格。

2、注释

2.1 注释风格

        1、注释可以让别人一看你的代码就明白其中的含义和用法，一般你的注释应该告诉别人代码做了什么。
        2、注释要放到函数的头部，使用        /* .........  */        这种方式

        3、对于多行注释，应该选择如下风格：

/*
* This is the preferred style for multi-line
* comments in the Linux kernel source code.
* Please use it consistently.
*
* Description: A column of asterisks on the left side,
* with beginning and ending almost-blank lines.
*/

        每一行的开始处都应该放置符号“*”， 并且所有的行的“*”要对齐在一列上.

2.2 文件信息注释

        在文件开始的地方应该对本文件做一个总体的、概括性的注释，比如：版权声明、版本号、作者、文件简介、修改日志等，如下所示的注释：

/*************************************************
Copyright © zuozhongkai Co., Ltd. 1998-2018. All rights reserved.
File name:      // 文件名
Author：        //作者
Version:        //版本号
Description:    // 用于详细说明此程序文件完成的主要功能，与其他模块
                // 或函数的接口，输出值、取值范围、含义及参数间的控
                // 制、顺序、独立或依赖等关系
Others:         // 其它内容的说明
Log:            // 修改日志，包括修改内容，日期，修改人等
*************************************************/

2.3 函数的注释

        函数需要注释其作用，参数的含义以及返回值的含义，注释可以放在函数声明的地方，也可以放在函数头，如下：

/*
*@ Description: 函数描述，描述本函数的基本功能
* @param 1 – 参数 1.
* @param 2 – 参数 2
* @return – 返回值
*/

三、标识符命名

1、命名规则

        1、在Linux命名风格是单词用小写，然后每个单词用下划线“_”连接在一起，比如:read_adc1_value()，因此在函数和变量的命名上就要使用此种方法，这也是 Linux 内核里面所使用的命名方法。
        注意：

        1、命名一定要清晰！清晰是首位，要使用完整的单词或者大家都知道的缩写。
        2、除了常用的缩写以外，不要使用单词缩写，更不要用汉语拼音！！！
        3、具有互斥意义的变量或者动作相反的函数应该是用互斥词组命名，如：

add/remove    begin/end            create/destroy          insert/delete
first/last    get/release          increment/decrement     put/get add/delete
lock/unlock   open/close           min/max                 old/new
start/stop    next/previous        source/target           show/hide
send/receive  source/destination   copy/paste              up/down

        4、不要使用单字节命名变量，但是允许使用 i， j， k 这样的作为局部循环变量。

2、文件命名

        文件统一采用小写命名。

3、变量命名

        变量名一定要有意义，并且意义准确，单词都采用小写，用下划线“_”连接。比如表示图
书的数量的变量，就可以使用如下命名：

int number_of_book;

不要采用匈牙利命名法，尽量避免使用全局变量。

4、函数命名

        和变量命名一样。

5、宏命名

对于数值等常量宏定义的命名，建议使用大写，单词之间使用下划线“_”连接在一起，比如：

#define PI_ROUNDED 3.14

四、函数

        函数要简短而且漂亮、并且只能完成一件事，函数的本地变量数量最好不超过 5-10 个，否
则函数就有问题，需要重新构思函数，将其分为更小的函数。

1、一个函数只完成一个功能

        如果一个函数实现多个功能的话将会给开发、使用和维护带来很大的困难。

2、重复代码提炼成函数

        一定要消除重复代码，将其提炼成函数。

3、函数集中退出方法（goto）

int fun(int a)
{
    int result = 0;
    char *buffer;
    buffer = kmalloc(SIZE, GFP_KERNEL);
    if (!buffer)
        return -ENOMEM;
    if (condition1) {
        while (loop1) {
            ...
        }
        result = 1;
        goto out_buffer;
    }
.....
 
out_buffer:
    kfree(buffer);
    return result;
}

4、对函数的错误返回要做全面的处理

        一个函数一般都会提供一些指示错误发生的方法，一般都用返回值来表示，因此我们必须
对这些错误标识做处理。

5、源文件范围内定义和声明的函数，除非外部可见，否则都应该用 static 函数

        如果一个函数只在同一个文件的其它地方调用，那么就应该用 static， static 确保这个函数只在声明它的文件是可见的，这样可以避免和其它库中相同标识符的函数或变量发生混淆。

五、变量

1、一个变量只能有一个功能

        一个变量只能有一个特定功能，不能把一个变量作为多用途使用。

2、不用或减少全局变量

        单个文件内可以使用 static 修饰的全局变量，这可以为文件的私有变量， 全局变量应该是模块的私有数据，不能作用对外的接口，使用 static 类型的定义，可以防止外部文件对本文件的全局变量的非正常访问。直接访问其它模块的私有数据，会增强模块之间的耦合关系。

3、防止局部变量和全局变量重名

        局部变量和全局变量重名会容易使人误解！

4、严禁使用未初始化的变量作为右值

        如果使用变量作为右值的话，在使用前一定要初始化变量，禁止使用未经初始化的变量作为右值，而且在首次使用前初始化变量的地方离使用的地方越近越好！未初始化变量是 C 和C++最常见的错误源，因此在变量首次使用前一定要确保正确初始化，

5、明确全局变量的初始化顺序

        系统启动阶段，使用全局变量前，要考虑到全局变量该在什么地方初始化！使用全局变量
和初始化全局变量之间的时序关系一定要分析清楚！

6、尽量减少不必要的数据类型转换

        进行数据类型转换的时候，其数据的意义、转换后的取值等都有可能发生变化，因此尽量
减少不必要的数据类型转换。

第六章 宏和常量

1、宏命名

        用于定义常量的宏的名字及枚举里的标签需要大写，在定义几个变量的常量时，最好使用枚举。

2、函数宏的命名

        宏的名字一般用大写，但是形如函数的宏，其名字可以用小写，如果能写成内联函数的就
不要写成像函数的宏。如下所示：

#define macrofun(a, b, c) \
        do { \
            if (a == 5) \
                do_this(b, c); \
        } while (0)

3、使用宏的注意事项

1、 避免影响控制流程的宏，

2、 作为左值的带参数的宏： FOO(x) = y，如果有人把 FOO 变成一个内联函数的话，这种

用法就会出错了。

3、忘记优先级：使用表达式定义常量的宏必须将表达式置于一对小括号之内

4、将宏所定义的多条表达式放在大括号中

        如果有多条语句的话，可以通过大括号来解决。

#define FOO(x) { \
    printf("arg is %s\n", x); \
    do_something_useful(x); \
}

5、常量建议使用const定义来代替宏