嵌入式C编程规范

背景

C语言是嵌入式开发常用的语言工具，C程序员都知道C是一种灵活而强大的语言，另一方面强大的功能也带来一定的复杂性，并使代码出现bug或者难以维护。这份编程规范的目的在于通过规范哪些可以做哪些不可以做来管理C代码的复杂性，同时在可管理的基础上提高大家使用C语言的生产力。

编程规范，英文style，也可以叫做代码的可读性，是一种通过一些规范来管理我们代码的方法。我们保持代码可管理的基础是保持代码的一致性，这会使你阅读别人代码的时候可以快速理解。通过这份规范，帮助大家保持自己编写的代码简洁、风格和类型一致，同时提高代码质量。

需要注意的是，这并不是一篇C语言教程，我们假设读者对C语言已经很熟悉了。

参考文献：google C++编码规范

注释

虽然大家可能觉得写注释很麻烦，但是注释对保持代码可读性至关重要。这部分的规范将告诉你哪些需要加注释并且注释要加在哪里。当写注释的时候，要写给你的读者----也就是下一个拿到你代码要进一步维护或者开发的工程师，一般来说，下一个拿到这份代码的人很可能就是你自己！
Icon

尽管注释非常重要，但是最好的方法还是让代码自身可读。通过给一个类型或者变量一个清晰明了的命名要好于使用一个简化或者难懂的命名然后在旁边加上注释解释。

注释规范

在C语言中，注释有两种规范：//或者/**/，这两种任何一种都可以，但是要保持前后一致。

文件注释

在每个.c或者.h文件起始的位置的注释，主要包含一个许可的模板和对于文件内容的描述。格式模板如下：

* Copyright 2014  Kingyee Technology Co., Ltd.

在第一行填写文件名，之后在Description后增加对于文件内容的描述，Auther后增加开发人员的名称，下面跟着创建日期，在Updates里面可以增加一些修改记录。

在INCLUDES下面列引用的头文件，头文件的顺序按照：C语言库、其他引用库、项目本身的.h顺序添加。

在CONSTANTS下面写宏定义，枚举等常量定义。

在LOCAL VARIABLES下面放置typedef、struct、定义的全局变量和引用，顺序也按照这个来。

一般来说，在.h头文件中主要是描述一些声明的函数或者结构他们是做什么用的，怎么使用。在.c文件中描述要更详细一些，包含实现细节或者关于一些技巧、算法的说明。注意.c和相关联的.h文件中的描述内容不要重复。

函数注释

在函数声明的地方增加注释简要描述函数的用途，在函数的定义处增加注释描述函数的操作。

在每个函数声明的地方需要增加注释描述函数有什么功能和如何使用函数，这些注释应是描述性质的，但是并不说明函数的原理。一些函数声明注释需要包含的信息有：
函数的输入和输出是什么
如果函数分配了内存那么调用函数后需要注意释放
函数中的任何参数是否可以为空指针
如果函数是可重入的，那么函数的同步前提是什么

在每个函数定义的地方需要增加注释描述函数如何实现功能的，例如在函数中使用了哪些编程技巧或者为什么这样实现功能。这里重点不是描述功能而是如何实现。看下面的例子：

其他注释

对于变量，一般来说，变量名应该足够描述变量的用途，在某些情况下，还是需要增加注释描述。

对于代码行，需要在一些代码编写技巧、不明显的功能实现或者用途处增加注释。

注释一般加在上方或者右侧，当代码加在右侧时，注意要有两个空格。

命名规范

保持代码一致性的重要途径是管理命名，通过命名应该可以直观的看出表示的是什么，而不需要再查找声明。通常来说命名是很随意的，但是为了保持整体代码的一致性以提高代码的可读性，不管大家的命名习惯是什么，这里我们统一规范。

通用命名规则

函数命名、变量命名和文件命名应尽量清晰明了，具有描述性，避免过渡缩写。尽可能的给出描述性名称，不要太节约空间，相比起来让别人清楚明白你的命名更重要。

文件命名

文件命名应全部采用小写，可以包含下划线或者破折号。一般来说文件命名尽量具有指向性，例如：http_server_logs.c要比logs.c更清晰。

函数命名

函数命名应该能体现该函数完成的功能，建议采用动词+名词的形式。关键部分应该采用完整的部分，辅助部分若太常用可采用缩写，缩写应符合英文的规范。每个单词的第一个字母大写。

同时函数的规模应尽量限制在200行以内。

变量命名

变量命名全部采用小写，单词之间可以包含下划线，结构体定义或者类型定义采用第一个单词小写之后每个单词的第一个字母大写，对于结构体的定义要求写类型名，并且以_tag结尾，对于宏定义的常量采用全部大写的方式，单词间可以增加下划线。

除非必要，不要用数字或较奇怪的字符来定义标识符。用宏定义表达式时，要使用完备的括号，将宏定义的多条表达式放在大括号中。

程序效率

待完善。