这样写C程序注释是否规范？还需要再写一个文档说明么？真心求建议.

#ifndef INIFILE_H_INCLUDED
#define INIFILE_H_INCLUDED

#include <stdio.h>
#include "list.h"
#include "cstring.h"

//flag定义
extern const unsigned short int is_key_value;   //key=value行
extern const unsigned short int is_comment;     //注释行

typedef struct tag_ini_item
{
    string  key;                     //key值
    string  value;                   //value值
    string  comment;                 //注释值
    unsigned short int line_flag;    //行标志
}ini_item, *pini_item;

typedef struct tag_ini_section
{
    string  name;                   //小节名
    List    items;                  //key=value行或是注释行集合
}ini_section, *pini_section;

typedef struct tag_ini
{
    List sections;                  //小节集合
}ini, *pini;

/**

 *  接口功能:

 *      ini_load_file   --  加载ini文件内容到内存中

 *      ini_save_file   --  保存ini内容到文件中

 *      ini_get_value   --  获取小节下某键的值

 *      ini_set_value   --  设置小节下某键的值

 *      ini_add_section --  添加新小节

 *      ini_set_section --  重设小节名

 *      ini_del_section --  删除小节

 *      ini_set_key     --  设置键名

 *      ini_del_key     --  删除键

 *      ini_unload      --  释放ini结构所占内存

 */

int     ini_load_file(pini inis, const char *filename);
int     ini_save_file(pini inis, const char *filename);
int     ini_get_value(pini inis, String value, const char *section, const char *key);

int     ini_set_value(pini inis, const char *section, const char *key,
                   const char *value, const char *comment);

int     ini_add_section(pini inis, const char *section_name);
int     ini_set_section(pini inis, const char *old_name, const char *new_name);
int     ini_del_section(pini inis, const char *section_name);
int     ini_set_key(pini inis, const char *section, const char *old_key, const char *new_key);
int     ini_del_key(pini inis, const char *section, const char *key);
void    ini_unload(pini inis);

#endif // INIFILE_H_INCLUDED

 

可以的，只是应写确实需要的注释，一些很明显的东西就不要写了——避免过分注释。
分别对每个函数声明注释较好，写明用法、参数、返回的意义，如果有需要注意的地方，也写上。

我是个新手，我觉得好规范啊，值得学习啦～～呵呵。

这是搞注册表的东西吧？

先领分再说吧。

TongDeng大侠建议很好，那么这个头文件是否有过分注释的问题？自己觉得结构部分注释或许有点过分，但怕日后忘记了。每个函数的返回值，用途什么的，因为写在原文件中了，是否需要再写一个文档作专门的注释呢？
这是偶自己的实现片段：
是否有注释过分或是不够的问题？

/**

 *  IniFile_impl.c

 *

 *  功能：实现ini文件的基本操作

 *  作者：hellovfp

 *  时间：2011.8.18

 *  最后修改：

 *

 *  本实现依赖于链表和字符串数据结构。仅用于ascii普通ini格式文本

 *  文件的读写操作。如需支持utf-8,unicode编码的ini文件，请自行实

 *  现扩充，所有接口实现与系统无关。

 */

#include "IniFile.h"
#include "IniFile_impl.h"

const char * special_section = "#&#";            //特殊小节

const unsigned short int is_key_value   = 1;     //key=value行
const unsigned short int is_comment     = 2;     //注释行

/**

 *  功能：从ini文件加载内容

 *  参数：inis -- ini结构指针，filename -- 文件名

 *  返回：int值，0表示成功，inis结构填充ini内容

 *  备注：原内容中只有唯一的小节和唯一的键值将被加载

 */
int ini_load_file(pini inis, const char *filename)
{
    FILE *pfile_ini;

    assert(inis);
    pfile_ini = fopen(filename, "r");

    if( pfile_ini )
    {
        char buffer[BUFSIZ];
        int found = 0;
        ini_section section;

        inis->sections = list_create( sizeof(ini_section) );
        init_section(&section);
        string_assign(&section.name, special_section);
        list_add_back(inis->sections, &section);        //添加一个特殊小节存放最前面的注释行

        while( !feof(pfile_ini) )
        {
            fgets(buffer, BUFSIZ, pfile_ini);

            if(strcmp(buffer, "\n"))                   //过滤掉空行
            {
                string_trim(buffer);                   //切去非空行两边空白字符，空白行将过滤

                if( is_comment_line(buffer) )          //如果是注释行, 包含节内注释
                {
                    ini_item item;

                    init_item(&item);
                    string_assign(&, buffer);
                    item.line_flag = is_comment;
                    list_add_back(section.items, &item);

                    continue;
                }

                if( is_section_line(buffer) )               //如果是小节行
                {
                    string s;

                    string_init(&s);
                    parse_section(&s, buffer);              //解析小节名
                    if( is_unique_section(inis, &s) )       //唯一小节名才添加
                    {
                        init_section(&section);
                        string_copy(&section.name, &s);
                        list_add_back(inis->sections, &section);
                    }
                    string_destroy(&s);

                    found = 1;
                    continue;
                }

                if( is_key_line(buffer) && found == 1 )     //如果是key=value行
                {
                    ini_item item;

                    init_item(&item);
                    parse_key_value(&item, buffer);         //解析键值
                    item.line_flag = is_key_value;
                    if( is_unique_key(&section, &item.key) ) //唯一key键才添加
                    {
                        list_add_back(section.items, &item);
                    }
                    else
                    {
                        destroy_item(&item);
                    }

                    continue;
                }
            }
        }

        fclose(pfile_ini);
        return 0;
    }
    else
    {
        perror("出错，不能打开ini文件");
        return 1;
    }
}

不是注册表，ini的读写c实现，不想依赖系统，所以自己搞了个实现自己用，顺便练习c语言.

呵呵，回帖都有分的。

我也是新手，正在向Tong大侠请教，让我们共同进步。

先拿分，再请教~！~