c代码的风格

 

 

可实践的选择[一]

系统的风格：应用林锐--------------

高质量C++/C编程指南

 

 

地址http://man.chinaunix.net/develop/c&c++/c/c.htm

 

可实践的选择[二]

如下简单的风格

 

 

 

 

 

 

 

 

 

 

@file	档案的批注说明。
@author	作者的信息
@brief	用于class 或function的批注中，后面为class 或function的简易说明。
@param	格式为 @param arg_name 参数说明 主要用于函式说明中，后面接参数的名字，然后再接关于该参数的说明。
@return	后面接函数传回值的说明。用于function的批注中。说明该函数的传回值。
@retval	格式为 @retval value 传回值说明 主要用于函式说明中，说明特定传回值的意义。所以后面要先接一个传回值。然后在放该传回值的说明。

 

/**
     * @brief ExFunc3的简易说明
     *
     * ExFunc3()只传回参数输入的指针。
     *
     * @param c 传进的字符指针。
     * @retval NULL 空字符串。
     * @retval !NULL 非空字符串。
     */
    char * ExFunc2(char * c)
    {
        return c;
    }   

 

稍微提示一下：

retval是列举返回值的情况。

return只是说明返回值的意义。

 

 

 

 

下面我们准备一组example.h 及example.cpp 来说明Doxygen 批注的使用方式：

example.h:

    /**
     * @file 本范例的include档案。
     *
     * 这个档案只定义example这个class。
     *
     * @author garylee@localhost
     */
           
    #define EXAMPLE_OK 0   ///< 定义EXAMPLE_OK的宏为0。
   
    /**
     * @brief Example class的简易说明
     *
     * 本范例说明Example class。
     * 这是一个极为简单的范例。
     *
     */
    class Example {
        private:
            int var1 ; ///< 这是一个private的变量
        public:
            int var2 ; ///< 这是一个public的变量成员。
            int var3 ; ///< 这是另一个public的变量成员。
            void ExFunc1(void);
            int ExFunc2(int a, char b);
            char *ExFunc3(char *c) ;
    };
   
   
example.cpp:

    /**
     * @file 本范例的程序代码档案。
     *
     * 这个档案用来定义example这个class的
     * member function。
     *
     * @author garylee@localhost
     */
   
    /**
     * @brief ExFunc1的简易说明
     *
     * ExFunc1没有任何参数及传回值。
     */
    void Example::ExFunc1(void)
    {
        // empty funcion.
    }

    /**
     * @brief ExFunc2的简易说明
     *
     * ExFunc3()传回两个参数相加的值。
     *
     * @param a 用来相加的参数。
     * @param b 用来相加的参数。
     * @return 传回两个参数相加的结果。
     */
    int ExFunc2(int a, char b)
    {
        return (a+b);
    }
   
    /**
     * @brief ExFunc3的简易说明
     *
     * ExFunc3()只传回参数输入的指针。
     *
     * @param c 传进的字符指针。
     * @retval NULL 空字符串。
     * @retval !NULL 非空字符串。
     */
    char * ExFunc2(char * c)
    {
        return c;
    }   
   
上 面这两个档案很简单的说明了Doxygen 批注的使用方式。您可依照此要领在你自己的程序代码中加上对应的批注。其实，无论您有无使用Doxygen ，都不妨依照他的格式将批注写入，一方面是依照他的格式，并不会干扰您程序的运作。另一方面，Doxygen 所定义的都是基本程序批注应当要有的东西。撰写清楚的批注是好的程序设计师应当的工作。