标题: C/C++注释范本 [打印本页]

---

作者: shaonv    时间: 2015-1-1 23:43
标题: C/C++注释范本
据业内分析程序员大部分时间是花费在看代码中，而写代码往往占不到一半，由此可见代码编写者非常有必要遵循一些规范，也是便于代码的维护。
首先这里先贴出我总结的一个注释范本：
// File Header Notes
/*
*****************************************************************
*   @File Name :
*   @Copyright        (C/C++)
*   @Author    :
*   @DATE      :
*   @Brief     :
*   @Details   :
*   @Version   :
*   @Target    :
*   @ToolChain :
*   @Notes     :
*****************************************************************
*/

// Function Notes
/*
****************************************************************
*   @Function Name   :
*   @Brief           :
*   @Details         :
*   @Param[in]       :

*   @Param[out]      :

*   @RetVal          :

*   @Author          :
*   @Date            :
****************************************************************
*/

// Struct Notes
/*
****************************************************************
*   @Brief           :
*   @Details         :
*   @Author          :
*   @Date            :
****************************************************************
*/

// Macro Notes
/* * * */

是的，你看到的没有任何中文字。笔者不推荐写注释使用中文，一是不国际化，二是目前还存在不支持中文的编译器，三是不利于代码的移植（平台对中文的支持程度不同，会造成显示乱码等）。所以程序员还是老老实实的用英文写注释吧，而且还能增强自己的英文水平。一举多得，何乐而不为。
下面是我给大家举的几个注释的例子：
1.文件头注释
/* *****************************************************************
*   @File Name : Main.c
*   @Copyright        (C/C++)
*   @Author    : Bernie Liu
*   @DATE      : 2014-02-21
*   @Brief     : marquee(horse race lamp)
*   @Details   : User can set the rate and the direction;Key1 set
                       the rate,Key2 set the direction
*   @Version   : V0.01
*   @Target    : C8051F005
*   @ToolChain : Keil4
*   @Notes     :
*****************************************************************
*/
这个注释是比较简单的，在  @Details一栏并没有详细的讲述此文件所做的工作，程序员在注释文件头的时候可以比较详细的叙述此文件所能完成的功能

2.函数注释
/*
****************************************************************
*   @Function Name   : UserSetMarqueeRates
*   @Brief           : User set the Marquee's rates
*   @Details         : rates include 8 modes, 0~8
*   @Param[in]       : 1）BYTE rates,User set from Key1 tunner

*   @Param[out]      : Null

*   @RetVal          : Null

*   @Author          : Bernie Liu
*   @Date            : 2014-02-21
****************************************************************
*/
以上是对设置跑马灯的速度的一个函数，函数名是 UserSetMarqueeRates，输入参数只有1个，速度的模式值，简单明了，阅读这一看便知道此函数的作用

总结：为什么要注释这里就不再去搬大道理了，很简单，你的记忆力有限，代码不可能永远是你一个人在维护。牵扯到时间和团队的维护，形成一个良好的编程风格是对一个程序员的一个考验。坚持做下去，你就是一个好的程序员。

---

欢迎光临 (http://www.51hei.com/bbs/)

Powered by Discuz! X3.1