编程规范

showmaker

Ⅰ、写在前面
不知道大家有没有这样的感受：看到不规范（杂乱差）的代码，瞬间就没有看下去的欲望了。


# N$ P( z) z# t! F9 O4 d
( T# T" I5 [+ ?相信大家看到标题都应该能明白编程的规范及原则对于每一个软件开发的工程师来说是多么重要。
9 E: \% }5 s/ M, h( D) u. y
2 Q* b" w- z, G* [9 O+ E
# t( C+ T& Q% D: ]$ p
初学者编写测试程序、小的模块程序也许不能感受它的重要性；但有经验及大型项目开发的人就知道程序的规范性对他们来说是有多么的重要。

7 g3 V/ `" w0 G  V8 C$ _

Ⅱ、关于编程规范及原则
" F7 k" ~/ a( K4 a- B2 R编程规范也就是编写出简洁、可维护、可靠、可测试、高效、可移植的代码，提高产品代码的质量。

本文针对嵌入式，主要结合C语言编程的规范给大家讲述。
. q5 h1 a% N2 N% X


' A5 z. f1 {, B0 O2 r* y1.头文件
  r1 t# ~% i' u/ i$ K对于C语言来说，头文件的设计体现了大部分的系统设计，不合理的头文件布局是编译时间过长的原因。


( Z( J) S& }3 }% p' o, S' T
+ f8 J( m4 t( e8 T" e有很多人将工程中所有的头文件包含在一个include.h文件中，然后在每一个.c源代码文件中包含include.h头文件，这样做可以让代码看上去简洁，但实际忽视了编译效率问题，而且代码的可移植性也不好。
# u& f8 H0 N: |5 i+ N' z$ G# J* }

2 Z! {* Y1 S/ t0 A. @
原则：
. \) Q* E. R1 u1 y5 M
! G, w  B- W' X/ ^, nA.头文件中适合放置接口的声明，不适合放置实现；

0 T& C4 g2 t! }  y2 |* n2 m6 mB.头文件应当职责单一;
- h3 d5 b8 _% I
C.头文件应向稳定的方向包含。

- N) W+ \( P8 r& w3 \

规则：

A.每一个.c文件应有一个同名.h文件，用于声明需要对外公开的接口;
% `; d0 _, V. |$ @/ N
B.禁止头文件循环依赖;
% E2 A+ E/ E2 I( {
, ~) ?# M$ K- i% TC..c/.h文件禁止包含用不到的头文件;
4 h" [+ U8 t9 U8 a  d) O
& l; A9 Y; B* gD.头文件应当自包含;
9 ?3 n  Q% c& F. q
7 P+ p& j4 n) M" bE.总是编写内部#include保护符（ #define 保护）;
$ E2 B+ ?3 n# w3 F: i8 l
* s! t0 Q6 _( D, _) ]% gF.禁止在头文件中定义变量;
$ u  U& D# F3 S0 E: O0 t0 G
( h# _8 N0 E2 ~& N/ s' H! AG.只能通过包含头文件的方式使用其他.c提供的接口，禁止在.c中通过extern的方式使用外部函数接口、变量;

9 e9 M. s" t, l7 t& e/ M' RH.禁止在extern "C"中包含头文件。
0 K# P4 c- |! a5 E8 t8 m
/ A8 ~% }/ k& j' l0 B, e" o

建议：

/ K) K; t" ?2 g: D/ a- S4 W% lA.一个模块通常包含多个.c文件，建议放在同一个目录下，目录名即为模块名。为方便外部使用者，建议每一个模块提供一个.h，文件名为目录名;
( s6 M4 Q* h; R) b7 A
B.如果一个模块包含多个子模块，则建议每一个子模块提供一个对外的.h，文件名为子模块名（降低接口使用者的编写难度）;
) ]" r# @6 k6 M0 ?7 s
C.头文件不要使用非习惯用法的扩展名，如.inc;

7 M  G0 U( n2 A; V- w; S/ w  HD.同一产品统一包含头文件排列方式。


) P$ i3 d# N$ i& |+ s7 {0 g: l
2.函数
函数设计的要点：编写整洁的函数，同时把代码有效组织起来。
$ {. Q: \5 L+ J7 i) }# I, w
/ a+ K' B% r! f4 R' E1 ^函数整洁的要求：代码简单直接、不隐藏设计者的意图、用干净利落的抽象和直截了当的控制语句将函数有机组织起来。



原则：

A.一个函数仅完成一件功能;

& R5 J7 U# j) PB.重复代码应该尽可能提炼成函数.
$ Z* n% ]: D8 t# V  Y# p% }


0 c# y# t4 O  I8 r7 _+ A1 R' g3 j规则：

" M1 \7 h# O3 p. {  H4 [0 qA.避免函数过长，新增函数不超过100行（非空非注释行）;

B.避免函数的代码块嵌套过深，新增函数的代码块嵌套不超过4层;
( n1 {) d7 z# d1 G* o2 i
C.可重入函数应避免使用共享变量；若需要使用，则应通过互斥手段（关中断、信号量）对其加以保护;

D.对参数的合法性检查，由调用者负责还是由接口函数负责，应在项目组/模块内应统一规定;

& i8 B) S2 }$ o7 }3 bE.对函数的错误返回码要全面处理;

1 g+ e3 T# U: W8 v4 t, B$ m8 wF.设计高扇入，合理扇出（小于7）的函数;

G.废弃代码（没有被调用的函数和变量)要及时清除。
7 @4 Z2 V  S6 E, G


% z$ n8 H) w2 @0 L$ ?4 C3 x建议：

A.函数不变参数使用const;

B.函数应避免使用全局变量、静态局部变量和I/O操作，不可避免的地方应集中使用;

7 L9 b8 N! E6 W2 h1 p) U5 Q9 @: y. KC.检查函数所有非参数输入的有效性，如数据文件、公共变量等;
' G! z7 K& @0 i8 F0 b. k. [2 _/ u
5 R8 g' E; G4 f, FD.函数的参数个数不超过5个;
- s0 U: A6 J  h
& f' `: g3 D0 o% g  hE.除打印类函数外，不要使用可变长参函数;
1 z' N  l: S. P! Q! u  Q% I; M/ Z" s
5 E  W* _( h% _4 P+ I( sF.在源文件范围内声明和定义的所有函数，除非外部可见，否则应该增加static关键字。



" [+ s1 z6 {7 G3 t7 b3.标识符命名与定义
程序命名是一个关键，如果命名不规范，自己写的代码，时间长了恐怕连自己都不知道是什么意思了。
# B% p, \; ]6 S( [


+ q, \% P' y, ^3.1通用命名规则

% P8 m( d. b/ S$ D" A常见命名风格：
: z* f1 J. {1 W0 g$ {7 Q" ^7 \
) _2 g& H1 Q! TA.用下划线„_‟分割，如text_mutex;

B.大小写字母混用，如ReadRFCText。
" `* W+ Q5 r- \( [4 X  ~: h  V

1 ~: Y) C" `4 ?& {; _8 {# K
规则：
& o$ R8 j8 N4 |0 V/ h6 @2 v
5 h& m/ M+ A! ZA.标识符的命名要清晰、明了，有明确含义，同时使用完整的单词或大家基本可以理解的缩写，避免使人产生误解；

; r  f; C) u" t% S0 x6 S/ WB.除了常见的通用缩写以外，不使用单词缩写，不得使用汉语拼音;
: j  m# A$ {8 D
- j! q4 D) g5 V. Q. n) SC.产品/项目组内部应保持统一的命名风格.
( e2 Z5 p9 {9 q. Y. ^6 h


建议：
9 t3 S- Y( d' ~
A.用正确的反义词组命名具有互斥意义的变量或相反动作的函数等;
* N0 R# p: u6 |' W
5 P; s' j/ X+ sB.尽量避免名字中出现数字编号，除非逻辑上的确需要编号;
& P" N# q' p4 }1 Y. o
C.标识符前不应添加模块、项目、产品、部门的名称作为前缀;
. ]( i0 L5 d4 V
D.平台/驱动等适配代码的标识符命名风格保持和平台/驱动一致;
: \% [+ F* l) ?, [8 b
& U9 R( o2 ^3 s& \E.重构/修改部分代码时，应保持和原有代码的命名风格一致。
7 K5 H) |. r+ S/ Q# o

5 q1 }! G4 W2 I4 S
& {4 J$ G* F! [6 U3.2 文件命名规则
' [# y2 `9 ^5 o3 k
4 w. Q" K$ N! _# u: M因为不同系统对文件名大小写处理会不同，建议文件命名统一采用小写字符。

! T1 {7 v# p7 T4 v7 k( }" U6 E
3 k$ W9 l" u' o& z
& P/ ?! a; m' \3.3 变量命名规则
7 n, W4 r5 j& F9 L; x/ C6 M; \. n
首先，全局变量十分危险，通过前缀使得全局变量更加醒目， 促使开发人员对这些变量的使用更加小心。

7 n4 D8 G7 P5 A& d* V( _- }其次，从根本上说，应当尽量不使用全局变量，增加g_和s_前缀，会使得全局变量的名字显得很丑陋，从而促使开发人员尽量少使用全局变量。
0 X+ D! v/ F! v) q) |5 {: g" \


6 L, N6 g, J7 B$ W3 ^规则：

A.全局变量增加“g_”前缀，静态变量增加“s_”前缀;

B.禁止使用单字节命名变量，但允许定义i、 j、 k作为局部循环变量;
! j/ w. f$ T" j% U7 ~( U% b% }
. u5 q8 S; m9 Y  R) ^C.使用名词或者形容词＋名词方式命名变量。
/ q  G4 `( `3 b1 }4 G

5 o5 s. T0 [, l1 V0 O8 g
0 q1 i: M. E! u& S3.4 函数命名规则
7 U& h4 \" ^% F/ M: Y
A.函数命名应以函数要执行的动作命名，一般采用动词或者动词＋名词的结构;

B.函数指针除了前缀，其他按照函数的命名规则命名。
3 K' u  ]- k5 X
8 m" G8 g# a/ x% x: p

3.5 宏的命名规则
. Q+ l8 H  R1 d! U) B$ m) I$ o9 r
6 A: ?5 M4 Y/ d- G4 X$ s+ dA.对于数值或者字符串等等常量的定义，建议采用全大写字母，单词之间加下划线„_‟的方式命名（枚举同样建议使用此方式定义）;

2 O' z: j2 y1 p/ VB.除了头文件或编译开关等特殊标识定义，宏定义不能使用下划线„_‟开头和结尾。
( t  s+ T# Q) Y% S; ]( u
6 V" L. `7 K. f: t
* o6 ^* w: ~% Z
4.变量
原则：

A.一个变量只有一个功能，不能把一个变量用作多种用途;
! Q+ y% n% z3 A( }; a% I' _* V
B.结构功能单一；不要设计面面俱到的数据结构;
# O) O& V' `3 i
: O7 a2 c7 s4 W; XC.不用或者少用全局变量。


+ g" D' O+ ~' T2 j/ B: w
2 S/ t1 A: e' P1 S: X( i规则：

0 l/ H+ i4 }* }A.防止局部变量与全局变量同名;
8 L0 q" A3 w6 M; u" }
B.通讯过程中使用的结构，必须注意字节序;
( K3 u) M( t6 K; y# s9 Z
C.严禁使用未经初始化的变量作为右值;
, t) Z- y) W1 ~5 y" ]& H
' a0 V1 ?0 r9 G

建议：

A.构造仅有一个模块或函数可以修改、创建，而其余有关模块或函数只访问的全局变量，防止多个不同模块或函数都可以修改、创建同一全局变量的现象;
! _6 b: u6 {! o( e" J5 a
B.使用面向接口编程思想，通过API访问数据：如果本模块的数据需要对外部模块开放，应提供接口函数来设置、获取，同时注意全局数据的访问互斥;

4 X" i1 m  _. N- NC.在首次使用前初始化变量，初始化的地方离使用的地方越近越好;

. z# B- j' p* a- J: k3 ]D.明确全局变量的初始化顺序，避免跨模块的初始化依赖;

E.尽量减少没有必要的数据类型默认转换与强制转换。

. z5 `; z& h* m, L8 j3 ?7 O
) V* W" d7 r+ t* ]. y' a- a# F/ F
0 A/ a+ Y' S- d* I, x5.宏、常量
因为宏只是简单的代码替换，不会像函数一样先将参数计算后，再传递。
5 @. M8 r, H4 |; R8 e( l
# [" N- D# [1 W

! G# I. j8 r0 @' }' g5 ~规则：
# Y: s2 s* N1 F6 D1 v! J
A.用宏定义表达式时，要使用完备的括号;

! q; e, q- W1 |1 X% w7 N3 \: g1 f不规范：#define RECTANGLE_AREA(a, b) a * b
) ?" l! E7 X( v
" X  {5 ]2 P# v5 U& m, d) T* r规范：#define RECTANGLE_AREA(a, b) ((a) * (b))
$ \- Z9 B( q) P$ |
1 M) Y6 r  Z4 G$ [- F" B; J9 {
' }  F4 S7 g: M% N/ t
B.将宏所定义的多条表达式放在大括号中;
$ Z3 p2 c! B9 c  _
C.使用宏时，不允许参数发生变化;
3 d7 S- Z7 y* j! n$ m
+ |) y! Q) |" I" {' {#define SQUARE(a) ((a) * (a))
, L  V$ m, k: {" {
- D5 L5 m& S5 O. e$ [/ k  k1 ]int a = 5;
- J8 O3 C9 G7 X4 q, u4 f
int b;
  a6 g: M( u, j0 }; t/ ~9 v
不规范：
8 N& @8 p. f. `: R9 V
; A( t/ k7 ]# s# Zb = SQUARE(a++);

$ q, \0 x5 B4 h7 T

6 q' G1 B; A. P7 i5 J3 W" X规范：
# y' r/ J/ ^: q) P4 T  N' X  v
b = SQUARE(a);
0 r2 n2 V) g/ K4 A" i0 @! ^, Q
- V/ k+ s$ |! h) a( ya++;
" E4 N0 e2 `4 D5 J: D
% P1 }4 I/ m" e7 ]' H
) k9 P+ y, |0 w3 M, F
4 s6 W: x* ]" A; G  W  k% r( s( m建议：
2 S8 q9 L3 X1 ]
8 a* M1 j5 M! ^5 m: v% S) QA.除非必要，应尽可能使用函数代替宏;
$ U1 G+ o) e$ i! z9 c% ?5 S9 I
B.常量建议使用const定义代替宏;
1 l( d, E* K# c+ G8 I/ s0 C2 U
C.宏定义中尽量不使用return、 goto、 continue、 break等改变程序流程的语句。
7 U1 t' H; K' [" r& S" K9 U

, `3 {) Z9 z, n0 ^% J
6.注释
: X. E( ^& ]: k8 \- l5 l2 b原则：
/ C' ]  F3 t0 x2 u! a2 X
A.优秀的代码可以自我解释，不通过注释即可轻易读懂;

1 r. b' K. d1 \+ q/ sB.注释的内容要清楚、明了，含义准确，防止注释二义性;
- v4 K% x2 l$ w) z1 \  I2 G
C.在代码的功能、意图层次上进行注释，即注释解释代码难以直接表达的意图，而不是重复描述代码。
3 u6 F! `0 m+ h4 L; Z* ^+ h
规则：

& |! c( V- a5 e7 w  \( b. Z& }A.修改代码时，维护代码周边的所有注释，以保证注释与代码的一致性。不再有用的注释要删;

B.文件头部应进行注释，注释必须列出：版权说明、版本号、生成日期、作者姓名、工号、内容、功能说明、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明;
C.函数声明处注释描述函数功能、性能及用法，包括输入和输出参数、函数返回值、可重入的要求等；定义处详细描述函数功能和实现要点，如实现的简要步骤、实现的理由、 设计约束等;
D.全局变量要有较详细的注释，包括对其功能、取值范围以及存取时注意事项等的说明;
: }7 |0 Z$ S$ u' A* ?0 pE.注释应放在其代码上方相邻位置或右方，不可放在下面。 如放于上方则需与其上面的代码用空行隔开，且与下方代码缩进相同;
F.避免在注释中使用缩写，除非是业界通用或子系统内标准化的缩写;
G.同一产品或项目组统一注释风格。
9 L2 A) u1 G' J% _建议：
" V8 M: l! S6 H1 _9 ~5 l; vA.避免在一行代码或表达式的中间插入注释;
; F3 y/ q" q! H& e7 C1 YB.文件头、函数头、全局常量变量、类型定义的注释格式采用工具可识别的格式。
4 p9 ]; v, }" t 7.排版与格式
规则：
% X+ N  M! I$ k- d
A.程序块采用缩进风格编写， 每级缩进为4个空格;

B.相对独立的程序块之间、变量说明之后必须加空行;
4 ^/ Z% f  }$ ~; l
C.一条语句不能过长，如不能拆分需要分行写。一行到底多少字符换行比较合适，产品可以自行确定;

( V, _' \9 p+ ^$ b/ n$ [/ r. H- uD.多个短语句（包括赋值语句）不允许写在同一行内，即一行只写一条语句;

1 S% L! i: Z1 U: A% HE.if、 for、 do、 while、 case、 switch、 default等语句独占一行;

! I/ r5 b3 J- U; ]! v1 AF.在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格； 进行非对等操作时，如果是关系密切的立即操作符（如－>），后不应加空格;
G.注释符（包括„/*‟„//‟„*/‟）与注释内容之间要用一个空格进行分隔。

muzitongxue

对于C语言来说，头文件的设计体现了大部分的系统设计，不合理的头文件布局是编译时间过长的原因

RNGxiaohu

一个模块通常包含多个.c文件，建议放在同一个目录下