| 网站首页 | 业界新闻 | 小组 | 威客 | 人才 | 下载频道 | 博客 | 代码贴 | 在线编程 | 编程论坛
欢迎加入我们,一同切磋技术
用户名:   
 
密 码:  
共有 1270 人关注过本帖
标题:今日散分帖,顺便问个程序注释问题。
取消只看楼主 加入收藏
hellovfp
Rank: 16Rank: 16Rank: 16Rank: 16
等 级:禁止访问
威 望:30
帖 子:2976
专家分:7697
注 册:2009-7-21
结帖率:98.48%
收藏
已结贴  问题点数:100 回复次数:16 
今日散分帖,顺便问个程序注释问题。
这样写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

 
搜索更多相关主题的帖子: color 
2011-08-19 11:36
hellovfp
Rank: 16Rank: 16Rank: 16Rank: 16
等 级:禁止访问
威 望:30
帖 子:2976
专家分:7697
注 册:2009-7-21
收藏
得分:0 
回复 2楼 TonyDeng
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;
    }
}

我们都在路上。。。。。
2011-08-19 12:02
hellovfp
Rank: 16Rank: 16Rank: 16Rank: 16
等 级:禁止访问
威 望:30
帖 子:2976
专家分:7697
注 册:2009-7-21
收藏
得分:0 
回复 4楼 TonyDeng
不是注册表,ini的读写c实现,不想依赖系统,所以自己搞了个实现自己用,顺便练习c语言.

我们都在路上。。。。。
2011-08-19 12:04
hellovfp
Rank: 16Rank: 16Rank: 16Rank: 16
等 级:禁止访问
威 望:30
帖 子:2976
专家分:7697
注 册:2009-7-21
收藏
得分:0 
回复 5楼 a9517495424
呵呵,回帖都有分的。

我们都在路上。。。。。
2011-08-19 12:05
hellovfp
Rank: 16Rank: 16Rank: 16Rank: 16
等 级:禁止访问
威 望:30
帖 子:2976
专家分:7697
注 册:2009-7-21
收藏
得分:0 
回复 3楼 章文2010
我也是新手,正在向Tong大侠请教,让我们共同进步。

我们都在路上。。。。。
2011-08-19 12:06
hellovfp
Rank: 16Rank: 16Rank: 16Rank: 16
等 级:禁止访问
威 望:30
帖 子:2976
专家分:7697
注 册:2009-7-21
收藏
得分:0 
唉,随着c文件越来越多,文件注释问题变得越来越纠结了,象c库函数一样写基本的头,然后再写个html专门写每个函数的用途,返回值简介?

我们都在路上。。。。。
2011-08-19 12:23
hellovfp
Rank: 16Rank: 16Rank: 16Rank: 16
等 级:禁止访问
威 望:30
帖 子:2976
专家分:7697
注 册:2009-7-21
收藏
得分:0 
以下是引用TonyDeng在2011-8-19 12:35:33的发言:

6楼的注释不错了,只是尚欠清晰。如果程序不是很简单,则纯注释某一行的作用不大。你已经将相对集中的功能段用空行分隔,那么可以注释这个段干什么的,而不用注释具体行和语句,因为那很可能要改的(可能是代码出错或别的补充原因),但段的意图是不会变的,阅读者根据注释检查代码是否实现意图即可,而不是根据代码猜测意图。

接口处的注释,是给调用者看的,因为那是头文件,对外公开,重点是如何使用。在实现代码文件,重点才是如何实现。这点你基本做到了。
有道理,注释一下大段的意图,免得日后对整个功能的流程意图阅读再回想!感谢Tong大侠的指导,偶再改改。

我们都在路上。。。。。
2011-08-19 12:41
hellovfp
Rank: 16Rank: 16Rank: 16Rank: 16
等 级:禁止访问
威 望:30
帖 子:2976
专家分:7697
注 册:2009-7-21
收藏
得分:0 
回复 15楼 QQ346957135
唉,先前偶也这样想过,不过后来吃了亏,n早以前写的代码,回头来读,结果自己都搞不清楚了。
总算明白程序不只是自己读的,别人也要读,所以现在苦练注释。

我们都在路上。。。。。
2011-08-19 13:27
hellovfp
Rank: 16Rank: 16Rank: 16Rank: 16
等 级:禁止访问
威 望:30
帖 子:2976
专家分:7697
注 册:2009-7-21
收藏
得分:0 
回复 16楼 zhoufeng1988
呵呵,受教了,偶再仔细的阅读一下代码注释规范,选一种做为自己的终身标准吧。以后有很多的问题还向周版主请教,还望到时不吝赐教。学习求进步,相比于昨天的我,今天比昨天好,就是进步。

我们都在路上。。。。。
2011-08-19 13:35
hellovfp
Rank: 16Rank: 16Rank: 16Rank: 16
等 级:禁止访问
威 望:30
帖 子:2976
专家分:7697
注 册:2009-7-21
收藏
得分:0 
回复 17楼 zhoufeng1988
感谢zhou版主的资料,收藏一下。
唉,至少“每一个变量声明都应该进行注释 [COMMENT-05-3] ”这个偶程序中就没有准循,继续努力。
这条国标 建议不使用单行注释“∥” [GJB5369-4_10_2_2-5] 让偶很纠结。


我们都在路上。。。。。
2011-08-19 13:40
快速回复:今日散分帖,顺便问个程序注释问题。
数据加载中...
 
   



关于我们 | 广告合作 | 编程中国 | 清除Cookies | TOP | 手机版

编程中国 版权所有,并保留所有权利。
Powered by Discuz, Processed in 0.023918 second(s), 8 queries.
Copyright©2004-2024, BCCN.NET, All Rights Reserved