代码开发注释规范

代码注释规范

下面为学习借鉴总结的一些不错的代码编写规范，记录在册，供自己遵循和回顾。

一、C/C++头文件（.h）

这里用来编写包括：宏定义、自定义类型、函数声明、类定义

1、文件描述

/*****************************************************************      个人习惯注释边长66个字符
* (c) Developed by Li Yingda. All rights reserved.
*
* @file: SysTick.h
*
* version: 1.1	2016-3-14
*
* This file contains the functions about the management of system
* tick timer which support parallel processing. Programmer can
* add as many tasks as the space and time permit to this modular
* by function SetTimeout() conveninently, so that programmer can
* get rid of the restriction of the number of system timer.
*
* Tips: The following function tick_interrupt should be added into
	the function SysTick_Handler in the object file stm32f10x_it.c
*****************************************************************/

2、头文件include信息

/************************ include files *************************/
#include "stm32f10x.h"

3、宏定义信息

/*********************** macro definitions **********************/
#define CALL_BACK_HANDLE callBackNode*

4、结构体、枚举、函数指针、自定义类型

/*********************** type definitions ***********************/
typedef void (*callBack)(void);

5、全局变量声明

/********************* variable declarations ********************/
int count;

6、类定义

/********************** class declarations **********************/
class node
{
private:
	int count;
public:
	get();
};

7、函数声明

/********************* function declarations ********************/
void SysTick_Init(void);

二、C/C++的.c/.cpp文件

这里用来编写：声明全局变量、函数的具体定义

1、文件描述

/*****************************************************************
* (c) Developed by Li Yingda. All rights reserved.
*
* @file: SysTick.h
*
* version: 1.1	2016-3-14
*
* This file contains the functions about the management of system
* tick timer which support parallel processing. Programmer can
* add as many tasks as the space and time permit to this modular
* by function SetTimeout() conveninently, so that programmer can
* get rid of the restriction of the number of system timer.
*
* Tips: The following function tick_interrupt should be added into
	the function SysTick_Handler in the object file stm32f10x_it.c
*****************************************************************/

2、头文件include信息

/************************ include files *************************/
#include "stm32f10x.h"

3、全局变量重声明

/********************* variable declarations ********************/
extern int count;

4、函数级注释、块注释、语句注释

/*****************************************************************
* This function can send a number to the server by GSM.
*
* @param	InstancePtr contains the pointer to the instance of the UART.
* @param	num is the number to be sent.
*
* @return	return TRUE if send successfully, otherwise FALSE
* @note		None.
*****************************************************************/
unsigned char TCP_Send_Int(XUartLite *InstancePtr, int num){
	unsigned char num_str[20];
	int count;
	/*
	* 块注释
	*/
	count = int_to_string(num, num_str);
	return TCP_Send(InstancePtr, num_str, count);	//语句注释
}