status

校对

ZoomQuiet

100%

1. CDay 0 时刻准备着!发布

~ 感受软件工程进行发布的准备

发布!为了全人类!

  • 因为一个人如果力求完善自己,他就会看到,为此也必须同时完善他人。一个人如果不关心别人的完善,自己便不可能完善。

1.1. 从需求导出用户群

小白已经实现的功能:

  1. 扫描光盘内容并存储为硬盘上的文本文件
    • 存储成*.cdc 的文本文件
    • 可以快速指定保存目录
    • 可以快速指定保存的文件名
  2. 根据储存到硬盘上的光盘信息计件进行搜索
    • 可以搜索指定目录中所有*.cdc文件
    • 可以指定关键字进行搜索
      • 列出所有含有关键字的信息行

对于大胆并逐渐习惯命令行界面的小白,现在的 PyCDC 基本可用了; 那么这样的小工具,有哪些人会愿意使用?

推想一下
  • 有很多光盘的人
  • 知道并会安装Python 的人
  • 不惧怕命令行的人
  • 勇于尝试的人

这样的人也必定是愿意分享的人,小白当然在行者多日的熏陶下,刚刚完成 可用的PyCDC 就想汇报给列表中的先辈们,获得夸奖,更加希望有人通过使用反馈意见,甚至于代码的改进意见,进而可以将自己首个作品长期发展下去,造福人类 ;-)

所以要发布!

1.2. 发布的本质

发布好象不是通告一嗓子就好的事儿

1.2.1. 给人用

小白尝试将 PyCDC 整理了个压缩包发送给朋友,结果所有的朋友都说不会使用...郁闷是小白的真实写照;

  • 询问列表:"怎么发布软件哪?!"
  • 行者回复:"文档!文档!文档!"

1.2.1.1. 文档!

分分分!学生的命根! 文档,文档,文档!软件的颜面!

  • 软件是给人使用的,但是你无法跑到每个愿意使用者身边,去演示如何使用你的软件吧?!
  • 所以,文档!友好的文档!清晰的文档!有效的文档! 就是作者的代言人,形象大使,是潜在参与/体验者的向导,来帮助他人学习/使用/改进你的软件的实用拐杖!
  • 对于使用相关许可证,进行源代码发布的自由软件;文档也是工程的一部分!面对乱七八糟的文档,是没有人敢于使用你的软件的...

1.2.2. 再次开发

所以,发布意味着针对你期望的用户再次开发!

  • 标准的自由软件包应该有哪些文档?
    1. AUTHORS 作者自述
    2. LICENSE 许可证类型(Python 世界喜欢简单的BSD系列许可证)
    3. README 软件说明
    4. ChangeLog 修订历史

    5. PKG-INFO 包信息 提供给一些自动程序使用

都是必须的类似八股文的....

  • 更加重要的,小白对自个儿经过反复尝试总结出来的多个小巧核心功能,至少有以下函式是非常期望有人可以重复使用的!
    • cdWalker()

    • cdcGrep()

    • _smartcode()

  • 那么如何更友好的说明如何单独使用这些函式? 进而,随着代码的频繁变化,怎样才能令这些函式便于维护?
  • 再问行者,才知道原来这叫:文档化开发 -- 将软件API文档同代码结合起来写,写代码的同时也完成了文档 -- 是种常用的开发维护同时进行的开发模式;

  • 文档化开发的主要技巧,就是利用注释!

详细:: 
PCS104 注释
进一步介绍了Python中注释的写法,
配合注释可以自动进行开发文档生成的工具...
  • 但是使用什么格式的注释?注释是通过什么工具转换成文档的?...

行者又推荐了::

1.2.2.1. epydoc

Easy Py Documentor -- 轻松的Py文档生成器!

  • http://wiki.woodpecker.org.cn/moin/CodeCommentingRule

  • http://epydoc.sourceforge.net/api/epydoc-module.html epydoc 自个儿的文档输出,是多么专业和规范哪

  • 简要的学习后,发觉只要起草一个简单的配置文件

    ##可以命名为epydoc.cfg
    [epydoc]
    # 项目信息
    name: PyCDC
    url: http://wiki.woodpecker.org.cn/moin/ObpLovelyPython
    
    # 想进行处理的文件或是模块,一般指定目录即可
    modules: /pat/to/pycdc.py,/pat/to/cdctools.py
    
    # 使用html 格式,输出文档到 apidoc/ 目录中
    output: html
    target: apidocs/
    
    # 指定 Graphviz dot.所在位置,可以生成各种UML关系图谱!(又一项自由环境中的福利!)
    graph: all
    dotpath: /usr/bin/dot
    
  • 这样一来小白可以随时使用类似命令

~$ epydoc --config epydoc.cfg获得最新的 API文档

  • 效果类似:

图 CDay0-1 epydoc生成的API文档

  • 是非常类似 JAVA DOC 的带框架的综合视图的文档站点!

详细:: 
PCS203 epydoc
进一步介绍了这一优秀的文档化开发支持工具;
所谓文档化开发,就是将软件工程过程中的相关文档,嵌入到相应代码的注释中,
通过简要的字串约定,然后由工具自动摄取出相应的文本,
组织成可以随时查阅的文档,

1.3. 引发的改进

1.3.1. 函式命名的合理性

自个儿之前随手命名的函式,在注释中,前后看起来并不顺畅,回想一路使用着的 Python 内置函式命名:

  1. os.listdir()
  2. os.walk()
  3. encode()
  4. open().write()

是多么的直接哪,果然,命名也是大学问:

  • Python开发编码规范

  • 简单说就是要应用先人们在大量代码编写中摸索出来的规范,可以令任何人快速在代码中区分出各种关键变量/类/函式等等
  • 原则,小白现在可以理解并习惯的
    1. 各种命令尽量使用动宾式短语
    2. 目录/文件名全部小写
    3. 类名使用 首字母大写单词串(WikiNames)

    4. 全局变量使用 全大写字串(CAPWORD)

    5. 函式 使用混合大小写串 (mixedCase)

    6. 内部变量,常数 全部小写
  • 综合应用就形如

   1 from mypacket import MyClass
   2 GLOBALVAR="是也乎"
   3 def doInsert(arg):
   4     MyClass.myFunc(GLOBALVAR)

详细:: 
PCS7 Python编码规范
完整的翻译了 pep-0008 Guido 原创的"Python风格指南"
http://www.python.org/dev/peps/pep-0008/
这是写出靠谱的Python脚本的基础中的基础素养,
至少应该认真反复精读3回的;

所以,小小修订一些变量/函式的命名更加贴切是作者在发布前的礼貌!?

  • cdctools._smartcode(stream)-> cdctools._smartcode(ustring)

  • codedetect = chardet.detect(ustring)["encoding"]->codename

1.4. 小结

通过本日故事小白正式登堂入室了软件工程世界, 沟通需要代价,改进由我作起!

  • 既然软件的发布就是和潜在的参与者的沟通,沟通就需要良好的媒介,在软件世界,软件工程文档是最好的中介;
  • 自由软件世界,聪明人太多,连文档也有专门的辅助工具,小白快乐的开始了使用和体验
  • epydoc 的体验将引导小白思考很多功能实现以外的事儿,令小白越来越不菜,行动更加有章法,向靠谱的程序员健康挺进..

1.5. 练习

  • (1) 请根据软件发布的流程和软件开发的编码规范,将读者之前章节写的程序修改并发布出去。另外,可以查找下除了epydoc外还有哪些较好的py文档生成器?


::-- ZoomQuiet [2007-04-13 16:14:09]

Name Password4deL ;) :( X-( B-)