FW开发代码规范---小任性（1）

---恢复内容开始---

　　使代码容易理解的方法无非是准确地注释和增强代码一致性。

　　一个好的准确的注释让代码容易理解是显然的。而代码的一致性，使编程风格统一，容易在内部形成一些共识、习惯用语和模式。

　　一、对代码进行注释再怎么强调也不过分。

（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          = 0, //Firmware Block
    BLOCK_FLAG_BLOCK_ALLOC       = 1, //Block Allocation Information
    BLOCK_FLAG_FACTORY_BAD_BLOCK = 2, //Factory Bad Block Table
    BLOCK_FLAG_NEW_BAD_BLOCK   = 3, //Bad Block Table and Remap Table
    BLOCK_FLAG_BOOT_A           = 4, //Block of Boot LU A 
    BLOCK_FLAG_BOOT_B           = 6, //Block of Boot LU B
    BLOCK_FLAG_RPMB             = 8, //Block of LU RPMB
    BLOCK_FLAG_SLC_SYSTEM      = 9, //Block For Sytem Data such as Map 
    BLOCK_FLAG_SLC_CACHE       = 10,//Block for Data Cache
    BLOCK_FLAG_TLC              = 11,//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 = 0;    

（5）代码注释：

　　边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。无用的过时的注释一定要删除！

　　 注释应与其描述的代码相邻。对语句块的注释必须放在语句块上方；对单条语句、变量定义的注释可以放在上方或右方（建议放在右方）；注释不可放在下方。

//The Number of commands that is pending for handling

Uint8 gCmdPendingNum = 0;    不良写法一,注释与代码之间有空行
______________________________________________________________________________________________________
Uint8 gCmdPendingNum = 0; 
//The Number of commands that is pending for handling    不良写法二，注释在代码下面
______________________________________________________________________________________________________
//The Number of commands that is pending for handling
Uint8 gCmdPendingNum = 0;    良好的写法

　　如果注释放在上方，则将注释与其上面的代码用空行隔开。

// 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）宏命名

　　宏命名全部大写，单词间使用下划线相连。