---恢复内容开始---
使代码容易理解的方法无非是准确地注释和增强代码一致性。
一个好的准确的注释让代码容易理解是显然的。而代码的一致性，使编程风格统一，容易在内部形成一些共识、习惯用语和模式。
一、对代码进行注释再怎么强调也不过分。
（1）通用规则：
注释是对代码功能的描述，代码则是对注释的实现，它们应该是一致的。
使用准确的英文表达最好。
如果确实需要在代码中使用新的缩写,新引入的缩写必须在文件头部加以说明。
注释格式尽量统一。建议使用//进行单行注释，多行注释可使用“/* …… */”。
（2）文件注释：
源文件（包含.h头文件、.c源文件及各种脚本文件等）头部应进行注释，应列出：版权说明、文件名、文件目的/功能，作者、创建日期等；如果源文件引入了新的缩写，则必须在文件头部注释说明。
文件注释格式定义如下（可以不局限于该格式中定义的内容，但必须包含该格式中定义的内容）：
/************************************************************
** Copyright (C) 2016-2017, XXX
** All rights reserved.
**
** FileName: // 文件名称
** Description: // 文件描述
** Author: // 作者
** Date: // 创建时间
** Others: // 其它说明
***********************************************************/ /************************************************************
Abbreviation: // 如果文件引入了新的缩写，则必须在此处加以说明
***********************************************************/
（3）函数注释：
函数头部应进行注释，需要列出函数的功能、参数、返回值等。函数注释格式定义如下（可以不局限于该格式中定义的内容，但必须包含该格式中定义的内容）：
/****************************************************************
Function: // 函数名称
Description: // 函数功能描述
Param: // 参数说明，包括参数的作用、取值范围等，格式如下：
param1: 输入输出类型[IN/OUT/INOUT] 说明
param2: 输入输出类型[IN/OUT/INOUT] 说明
…
Return: // 函数返回值说明
Others: // 其它说明
Author: // 作者
****************************************************************/
（4）数据注释：
对于所有有物理含义的变量、常量，如果其命名不是充分自注释的，在声明时都必须加以注释，说明其物理含义。变量、常量、宏的注释应放在其上方相邻位置或右方。
// active statistic task number
#define MAX_ACT_TASK_NUMBER 1000 #define MAX_ACT_TASK_NUMBER 1000 // active statistic task number
数据结构声明(包括结构体、枚举、类等)，如果其命名不是充分自注释的，必须加以注释。对数据结构的注释应放在其上方相邻位置；对结构中每个域的注释放在该域的右方。
//FLAGs used to Identify the block type
enum BLOCK_FLAG_ENUM
{
BLOCK_FLAG_FIRMWARE = , //Firmware Block
BLOCK_FLAG_BLOCK_ALLOC = , //Block Allocation Information
BLOCK_FLAG_FACTORY_BAD_BLOCK = , //Factory Bad Block Table
BLOCK_FLAG_NEW_BAD_BLOCK = , //Bad Block Table and Remap Table
BLOCK_FLAG_BOOT_A = , //Block of Boot LU A
BLOCK_FLAG_BOOT_B = , //Block of Boot LU B
BLOCK_FLAG_RPMB = , //Block of LU RPMB
BLOCK_FLAG_SLC_SYSTEM = , //Block For Sytem Data such as Map
BLOCK_FLAG_SLC_CACHE = ,//Block for Data Cache
BLOCK_FLAG_TLC = ,//Normal Data Block
BLOCK_FLAG_END //Not USED, Please Keep it at the last
};
全局变量必须有注释，包括对其功能、取值、及其他注意事项等的说明。
//The Number of commands that is pending for handling
Uint8 gCmdPendingNum = ;
（5）代码注释：
边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。无用的过时的注释一定要删除！
注释应与其描述的代码相邻。对语句块的注释必须放在语句块上方；对单条语句、变量定义的注释可以放在上方或右方（建议放在右方）；注释不可放在下方。
//The Number of commands that is pending for handling Uint8 gCmdPendingNum = ; 不良写法一,注释与代码之间有空行
______________________________________________________________________________________________________
Uint8 gCmdPendingNum = ;
//The Number of commands that is pending for handling 不良写法二，注释在代码下面
______________________________________________________________________________________________________
//The Number of commands that is pending for handling
Uint8 gCmdPendingNum = ; 良好的写法
如果注释放在上方，则将注释与其上面的代码用空行隔开。
|
// code one comments program code one // code two comments program code two |
//code one comments program code one // code two comments program code two |
过于紧凑 建议写法
避免在一行代码或表达式的中间插入注释。
对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释。
说明：这样比较清楚程序编写者的意图，有效防止无故遗漏break语句。
case CMD_A:
ProcessA();
break; case CMD_B:
ProcessB ();
// Fall through to case CMD_C case CMD_C:
ProcessC();
break;
注释与所描述内容进行同样的缩排。说明：可使程序排版整齐，并方便注释的阅读与理解。
|
void Example_Fun( void ) { //code one comments CodeBlock One //code two comments CodeBlock Two } |
void Example_Fun( void ) { // code one comments CodeBlock One // code two comments CodeBlock Two } |
不好的注释缩排 良好的注释缩排
二、命名
（1）通用命名规则
标识符的命名要清晰明了，有明确含义；命名应具有描述性；一般而言，类型和变量应是名词，函数应是“命令性”动词；
命名应使用使用完整的单词或大家可以理解的缩写，避免使人产生误解；如使用特殊约定或缩写，要有注释说明，可参见【规则2-1-5】；需注意避免过度缩写。当然约好的缩写除外
|
//良好命名 uint32 numError; uint32 numConnections; |
//过度缩写 uint32 nErr; uint32 nConns; |
（2）文件命名
文件名全部小写；为避免由于文件名过长造成难以理解，可以在适当位置使用下划线进行分隔。
|
不良的文件命名： mmieventmanager.h（过长难以理解） Star_HttpServer.h（大写字母） |
|
良好的文件命名： mmi_applet_table.h mmicc_speeddial.c |
（3）类型命名
结构体（struct）类型名遵循如下规则：全部字母大写，单词间使用下划线相连，以_S后缀结束；命名中的前缀、关键缩写词等可以适当的采取全部大写。
struct的typedef类型定义名遵循如下规则：和struct名采用相同命名，以_T后缀结束。一般而言，struct需同时定义类型名和typedef名，推荐同时为其定义指针类型。也可以不定义struct类型名
typedef struct FIFO_S //_S表示 struct
{
…
} FIFO _T, *pFIFO_T;
或者
typedef struct
{
…
}FIFO_T, *pFIFO_T;
枚举（enum）类型名遵循如下规则：全部字母大写，单词间使用下划线相连，以_ENUM后缀结束。
enum的typedef类型定义名遵循如下规则：和enum名采用相同命名，但全部字母大写，单词间使用下划线相连，并以_E后缀结束。
一般，enum无需定义类型名，仅需定义typedef名。
typedef enum BLOCK_FLAG_ENUM
{
…
} BLOCK_FLAG_E;
或者
typedef
{
…
} BLOCK_FLAG_E;
（4）变量命名
局部变量、全局变量、参数变量、成员变量，变量名使用驼峰命名法，首字母一律小写，从第二个单词开始首字母大写。
|
不良的命名： uint8 * strtable; //没有采用驼峰命名法 |
|
推荐的命名： AW_LCD_PARAM_T lcdParam; uint8 phoneNum[10]; |
静态全局变量建议使用s前缀，普通全局变量使用g前缀。指针型的变量前面加p前缀，复合前缀都用小写字母。
|
ATC_INFO_T gAtcInfoTable[10]; //普通全局变量 static BOOLEAN sBatteryStatus; //静态全局变量 uint8 * pStrTable; //指针型变量 static uint32 * spReturnAddress; //静态全局指针 uint32 * gpInputCommand; //普通全局指针 |
单个字符的变量名（如i、j、k等）仅用作局部循环变量。
|
单个字母唯一可使用的场合： for (i = 0; i < max; i++) { … } |
（5）常量命名
常量名全部字母大写，单词间用下划线隔开。
|
const float PI = 3.14; const int VAL_MIN = 1; |
（6）函数命名
函数名中每个单词首字母大写；为避免由于函数名过长造成难以理解，可以在适当位置使用下划线进行分隔；命名中的前缀、关键缩写词等可以适当的采取全部大写。
|
不建议的命名： charge_init(); //未采用正确的大小写规则 FEProcessReadCommand(); //函数名太长且没有分隔，造成理解困难 |
|
建议命名： Charge_Init(); FE_ProcessReadCommand (); //加适当的分隔 |
（7）枚举命名
枚举值全部大写，单词间使用下划线相连；枚举类型定义参见
（8）宏命名
宏命名全部大写，单词间使用下划线相连。