开发文档和程序注释

王志勇 发表于 2013年03月17日 11:06

我最近在开发一个全新的程序,工单系统(客服问答系统),第一次编写工单系统,后来发现还是要比想象中复杂不少,已经花了10天左右的时间,马上快要完工了。我写程序习惯于追求最简单的算法,然后使用最简洁的编写格式,完成需要的功能。然而简洁和易读,常常会不可兼得。开发文档和程序注释,实际上只是为其他的开发人员而编写。开发文档和程序注释,它们的区别是开发文档较具体,程序注释只是针对部分语句进行注释。

电脑软件/网站的程序设计和电路设计/IC芯片设计,我发现有很多十分相似的地方,设计的步骤和原理相似,都是像建一个楼房一样把各个原料累加起来、把各个部分连接起来。但不同的是,程序设计完成的成品,是运行在电脑当中,没有三维空间中的实物;电路设计/IC芯片设计完成的成品,在三维空间中可以看到实物。电路设计比如电脑主板、手机主板、硬盘电路、显卡、MP3主板、解码板的电路设计,等等。

编写一个项目的完整的开发文档,至少要花费开发时3~10倍,甚至20倍以上的时间。所以一般我们是看不到完整的开发文档的,因为没有人写。即使写出来了,公开发布,也只有极少数的人能够完全读懂,因为它是一个工程。任何人要完全读懂一个工程,都是要花费相当多的时间。比如开发一个功能较完整的Blog程序需要花费1000小时以上(我已经完成过这样的作品),合3个多月;那么编写与它相对应的完整的开发文档,篇幅要远远大于程序本身,所花的时间至少是1000小时乘以3~20倍,至少要用9个月到7年的时间才能完成这样的开发文档,这并不夸张,现实就是如此。

不要小看一个工单系统、短消息系统、邮件系统、Blog系统、新闻系统、论坛系统,这些系统都是对数据进行处理,但在开发当中常常会遇到大量的逻辑运算、统筹。当需要实现某个功能时,会做海量的测试,几乎每个步骤都会做测试,完成一个功能至少会经历几十次、上百次、几百次的测试,出错时,运行平台会报错。那么完成一个程序项目的开发,至少会经历几千次、几万次、几十万次的测试。因此,完成的程序成品,本身是一件十分精密的仪器

任何程序都可能不是完美的,所以需要进行升级。同样,电脑主板、手机主板、IC芯片等等的电路设计,也可能不是完美的。即使是一流的公司开发的程序,也可能不是完美的。都是平等的,随时都可能存在需要改进的地方,永无止境。

下图是我编写的工单系统里的一段程序截图,PHP语言。它的功能是,在工单系统的首页有已回复、处理中、已处理的3类链接,当用户发表新帖、或者回帖,这个帖会进入到“处理中”的分类;当客服回帖时,这个帖会进入到“已回复”的分类;用户读过客服的回复,这个帖会进入到“已处理”的分类。并且在工单系统首页这3个分类的总帖数,总和为30。当超过30个时,自动去掉“已处理”的最后一个帖子。由于时间的关系,这个截图只能用作欣赏,就像一个IC芯片一样无法一下子解释清楚,这个图就是我的真实的生活照,它是对上述这3类链接进行处理。如果要把这段程序完全解释清楚,至少要3-5篇的博客篇幅。写程序,很累很累很累,连续一两个月每天眼睛盯着电脑屏幕10个小时的生活是难以想象的。但它的乐趣在于能够实现你想要的功能,只是要花难以估量的时间。不写程序不行,它是我的饭碗和工作。

0条评论:

发表评论:
名字: (*必填)
博客: (可省)

正文:

  记住信息?

王志勇:1980-09-26 (44周岁)
程序设计,前端设计。

版权声明:本博客所有文章,均符合原创的定义,禁止转载,违者将必究;正确的方法是贴原文的标题和网址即可。

与此相关的链接
自由勇专栏

Blog存档 Archives

2022年07月
2022年06月(15)
2022年05月(20)
2022年04月(16)
2022年03月(9)
2022年02月(9)
2022年01月(10)
2021年 +

2020年 +
2019年 +
2018年 +
2016年-2017年(9)
2014年06月-09月(10)
2013年 +
2012年 +
2011年 +
2010年 +
2009年 +
2008年 +
2007年 +
2006年 +
2005年09月(4)

Copyright © 2006-2024 auiou.com All rights reserved.
此Blog程序由王志勇编写