嵌入式代码的注释问题

简介：

对于代码的规范性不管是做纯软件开发的还是做嵌入式开发的或者使用各种语言的，都是非常重要的。代码的规范性对编写人员对代码后期的维护以及其他开发人员阅读等都是非常友好的。接下来我们会对代码的规范性进行说明（当然，根据个人的情况和企业的不同可能要求不一样，我就根据我个人的一个情况进行一些说明，本专题不作为最终范本，仅用来作为参考）

注释问题

本篇就说说代码的注释问题，这东西就像去饭店吃饭一样，有菜单、指示牌等。注释就相当于这些，是对代码的一种说明。

头部注释

说明性文件（例如.h）

注释要列出下列几项：版权说明、版本号、生成日期、作者、内容、 功能、与其它文件的关系、修改日志等，头文件的注释中以及函数功能简要说明。

例如：

1/*****************************************************************************
 2Copyright (c) 2016  XXXXXXXXXXXXXXXXX., Ltd. All rights reserved.
 3
 4File name:/*文件名*/
 5Date      Author:       Version: /*作者、版本及完成日期*/
 6
 7Description:/*用于详细说明此程序文件完成的主要功能，
 8                与其他模块或函数的接口，输出值、取值范围、含义及参数间的控制、顺序、独立或依赖等关系*/
 9
10Others:/*其它内容的说明*/
11
12Function List:/*主要函数列表，每条记录应包括函数名及功能简要说明*/
131.…
14History:
15/*修改历史记录列表，每条修改记录应包括修改日期、修改者及修改内容简述*/
16
171. Date:
18Author:
19Modification:
202.…
21
22*****************************************************************************/

源文件头部注释

源文件头部注释要有版本说明、版本号等

版权说明、版本号、 生成日期、作者、模块目的/功能、主要函数、修改日志、修改人、修改日期等。

1/***********************************************************************
 2*   Copyright (C) company name  xxxCo., Ltd.                *
 3*                            All Rights Reserved.                      *
 4*   Department :                                          *
 5*   AUTHOR     : NSF                                                 *
 6************************************************************************
 7* Object        :
 8* Module        :
 9* Instance      :
10* Description   :/*模块描述*/
11*-----------------------------------------------------------------------
12* Version:
13* Date:
14* Author:  /*作者*/
15***********************************************************************/
16/*-History--------------------------------------------------------------
17* Version       Date         Name    Changes and comments
18*=====================================================================*/

函数头部注释

列出函数的作用、目的、输入输出参数等

1/************************************************* 
2Function: /* 函数名称*/
3Description: /* 函数功能、性能等的描述*/
4Input: /* 输入参数说明，包括每个参数的作用、取值说明及参数间关系。*/ 
5Output: /* 对输出参数的说明。*/
6Return: /* 函数返回值的说明*/
7Others: /* 其它说明，应标明是否是可重入函数*/
8*************************************************/

在写代码的同时，我们尽量编写代码编注释，同时修改代码也要有相对应的注释，目的是为了注释和代码的一致性（想想你把项目写完了再去注释，你还知道哪跟哪不？）

要对所有的变量、常量其命名不能够充分解释其代表的意义，要进行说明。

比如：

1/* active statistic task number */
2#define ACT_TASK_NUMBER 1000
3
4#define ACT_TASK_NUMBER 1000 /* active statistic task number */

数据结构声明(包括数组、结构、类、枚举等)，如果其命名不是充分自注释的，必须加以注释。对数据结构的注释应放在其上方相邻位置，不可放在下面；对结构中的每个域的注释放在此域的右方。

对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处理，必须在该case语句处理完、下一个case语句前加上明确的注释。

统一保存为UTF-8代码编码格式（这个任何编译器都有的，但是对于GB并不是所有的都支持） 。

在代码的功能、意图层次上进行注释，提供有用、额外的信息。