C潜规则篇之代码规范

    很多初学者写代码只关注语法正确，而不在乎代码书写的规范和风格，导致写出来的代码乱七八糟，不但别人连自己都不愿多看一眼。这种代码难以维护，难以重用，更无法修改，功能再好也没人敢用。因此良好的代码规范不是可有可无，它不仅起美化作用，更重要的是使代码易阅读，易维护，提高工作效率。那么怎样给代码美容，使其看起来更“职业”呢？

    除了上篇符号命名法外，前辈们在长期编程实践中总结出很多不成文的规范，教科书上肯定没有，但实际中很重要。当别人说你coding不规范，别不服气，更别说老师没教（是事实，但不是理由）。正规大公司都有专门coding_style培训，保证code一致性。前几天一个刚入职新人来问我公司有没有内部coding规范，我立马知道，这家伙C不会差到哪里去。怎样不在这方面失分？

代码对齐

    代码对齐是为了使代码美观，且有层次感。没有统一缩进和对齐的代码简直是视觉污染。具体对齐规则包括：

    1） 统一的大括号风格，即：

      if(){

      }与

      if()

      {

      }

    二者任选一种都可以，但要保持一致，不要在同一工程或文件中混用两种风格。

    2） 按照逻辑关系统一缩进4字符。

    3） 禁用TAB键做缩进，TAB键在不同编辑器上包含不同的空格数，有时4个有时2个，用TAB键缩进后，在某编辑器上整齐排列的代码放到另一种编辑器里就变得参差不齐，而重新调整后，回到原编辑器很可能又乱了。所以应该用空格缩进。

代码排列

     上班路上拥挤的地铁让人很不舒服，代码也一样，合理分散排列才会美观大方，具体：

    1）  单行只放一条语句，防止int a; float b; char c;这种一行多语句，int a, b, c;这种同类型多变量定义除外。

    2）  一本书章节清晰才能调动读者的兴趣，平铺直叙只会枯燥乏味。同样在代码中适当插入空行，分隔功能模块，也能提高可读性。比如for/switch case/while/if else等结构都应作为单独模块，与其他模块用空行分隔。

    3）  表达式符号间插入空格，如：if(((a-b)>0)&&((a+b)<c))应写成if( ( (a – b) > 0 ) && ( (a + b) < c) )。明显后者更清楚美观。而这只需要养成大拇指顺手按空格键的习惯就行。

代码注释

    C语言中注释有两种写法，“/* */”与“//”，其中“//”一般用于关键与疑难语句后，帮助读者理解单行语句。如果单行代码滥用/**/符号会形成“城中村”或“村中城”式的混乱，类似下面，更适合用//注释：

    /* This type of comment can lead to confusion especially when describing a function like*/

    ClkUpdateTime ().；/*The function looks like actual code! */

    下列两种场合一般用“/**/”，一是在程序核心源文件开头，对整个文件内容注释；二是关键函数前的注释。下面提供样例模板供参考，不要版权费哦

    1）文件头注释一般应包括：

    __ 文件名，文件类型以及版本和版权声明。

    __ 目的、功能说明。

    __ 修订日志，包括作者、修改日期、修改内容等。

例如：

/*

*******************************************************************************

* (c) Copyright 2010, XXX, Inc.

* All rights reserved. XXX Inc. and ………

*

* Filename : fileoperation.c

* Description : The following code is to implement file operation ………

* Modified History:

*   2010/02/13,   AuthorName,   initial version

*   2010/04/05   AuthorName,    …………

*   ……

*******************************************************************************

*/

    2）重要函数主要指程序主体模块函数，这类注释可包含：

    __ 函数功能描述与说明；

    __ 函数参数说明，包括参数含义及输入输出性质；

    __ 函数可重入性，即说明此函数是否可重入，即是否包含global或static型变量。可重入性对于多任务条件下的应用非常重要。

    __ 返回值及其代表的不同情况；

例如：

/*

*  Description:    Decode a input mp3 stream

*  Parameters:

*    pInbuf:  [input]     buffer contains input mp3 data

*    pOutbuf:[output]    buffer contains output pcm data

*    length:    [input]     input data length

*  Reentrant:     Yes(or not)

*  Return Value:

*    The actual length of output pcm

*    Negative value when an error occurs.

*/

int MP3Decode( void *pInbuf, void * pOutbuf, int length,);

    另外，对于一些关键的数据结构，例如程序核心结构体或类，也可以用/* */注释详细说明每个成员变量的含义、用途，因为关键结构体往往对理解整个程序起重要作用。

头文件与源文件中模块功能划分与顺序

    头文件中可能包含对其他头文件的包含、宏定义、函数声明、结构体定义等等内容，如果随意安排这些内容，会显得参差杂乱，可读性差。可排列如下：

1）#include其它头文件

2）#define公共宏

3）enum/structure

4）function declarion

同样源文件中也包含一些声明性质的元素，顺序一般安排如下：

1）版本声明和文件头注释

2）#include头文件

3）本文件私有的variable，enum和structure

4）本文件私有的#define

5）static函数的声明

    有人觉得这些规则过于细致和麻烦，请换位思考：当拿到一份代码，对用途和机制一无所知，迫切想找些提示信息时，如果除了排列混乱的代码外什么都没有，这时你会是什么感觉。相反，如果有源文件功能介绍和函数注释，代码排列整齐，功能划分清晰，又是什么感觉。

    代码的价值很大程度体现在能被多少人看懂且引用。作为软件工程师，我们应该有这样的信念：我们不单贡献生产力，同时也要为这个世界留下美。

轻松一刻：Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.-- Rick Osborne

 翻译：编程时，一定要想像一下，以后维护你写的代码的那个人会不会变成一个有暴力倾向的疯子，并且，他还知道你住在哪