status |
校对 |
100% |
1. CDay 0 时刻准备着!发布
~ 感受软件工程进行发布的准备
发布!为了全人类!
因为一个人如果力求完善自己,他就会看到,为此也必须同时完善他人。一个人如果不关心别人的完善,自己便不可能完善。
1.1. 从需求导出用户群
小白已经实现的功能:
- 扫描光盘内容并存储为硬盘上的文本文件
- 存储成*.cdc 的文本文件
- 可以快速指定保存目录
- 可以快速指定保存的文件名
- 根据储存到硬盘上的光盘信息计件进行搜索
- 可以搜索指定目录中所有*.cdc文件
- 可以指定关键字进行搜索
- 列出所有含有关键字的信息行
对于大胆并逐渐习惯命令行界面的小白,现在的 PyCDC 基本可用了; 那么这样的小工具,有哪些人会愿意使用?
- 推想一下
- 有很多光盘的人
- 知道并会安装Python 的人
- 不惧怕命令行的人
- 勇于尝试的人
这样的人也必定是愿意分享的人,小白当然在行者多日的熏陶下,刚刚完成 可用的PyCDC 就想汇报给列表中的先辈们,获得夸奖,更加希望有人通过使用反馈意见,甚至于代码的改进意见,进而可以将自己首个作品长期发展下去,造福人类
所以要发布!
1.2. 发布的本质
发布好象不是通告一嗓子就好的事儿
1.2.1. 给人用
小白尝试将 PyCDC 整理了个压缩包发送给朋友,结果所有的朋友都说不会使用...郁闷是小白的真实写照;
- 询问列表:"怎么发布软件哪?!"
- 行者回复:"文档!文档!文档!"
1.2.1.1. 文档!
分分分!学生的命根! 文档,文档,文档!软件的颜面!
- 软件是给人使用的,但是你无法跑到每个愿意使用者身边,去演示如何使用你的软件吧?!
- 所以,文档!友好的文档!清晰的文档!有效的文档! 就是作者的代言人,形象大使,是潜在参与/体验者的向导,来帮助他人学习/使用/改进你的软件的实用拐杖!
- 对于使用相关许可证,进行源代码发布的自由软件;文档也是工程的一部分!面对乱七八糟的文档,是没有人敢于使用你的软件的...
1.2.2. 再次开发
所以,发布意味着针对你期望的用户再次开发!
- 标准的自由软件包应该有哪些文档?
- AUTHORS 作者自述
- LICENSE 许可证类型(Python 世界喜欢简单的BSD系列许可证)
- README 软件说明
ChangeLog 修订历史
- PKG-INFO 包信息 提供给一些自动程序使用
都是必须的类似八股文的....
- 更加重要的,小白对自个儿经过反复尝试总结出来的多个小巧核心功能,至少有以下函式是非常期望有人可以重复使用的!
cdWalker()
cdcGrep()
_smartcode()
- 那么如何更友好的说明如何单独使用这些函式? 进而,随着代码的频繁变化,怎样才能令这些函式便于维护?
再问行者,才知道原来这叫:文档化开发 -- 将软件API文档同代码结合起来写,写代码的同时也完成了文档 -- 是种常用的开发维护同时进行的开发模式;
文档化开发的主要技巧,就是利用注释!
详细:: PCS104 注释 进一步介绍了Python中注释的写法, 配合注释可以自动进行开发文档生成的工具...
- 但是使用什么格式的注释?注释是通过什么工具转换成文档的?...
行者又推荐了::
1.2.2.1. epydoc
Easy Py Documentor -- 轻松的Py文档生成器!
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 内置函式命名:
- os.listdir()
- os.walk()
- encode()
- open().write()
是多么的直接哪,果然,命名也是大学问:
- 简单说就是要应用先人们在大量代码编写中摸索出来的规范,可以令任何人快速在代码中区分出各种关键变量/类/函式等等
- 原则,小白现在可以理解并习惯的
- 各种命令尽量使用动宾式短语
- 目录/文件名全部小写
类名使用 首字母大写单词串(WikiNames)
全局变量使用 全大写字串(CAPWORD)
函式 使用混合大小写串 (mixedCase)
- 内部变量,常数 全部小写
- 综合应用就形如
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]