标题: 关于下帖的所谓文档“规范”
carol
荣誉斑竹
Rank: 14Rank: 14Rank: 14Rank: 14
幻想懒王++


UID 1859
精华 66
积分 5139
帖子 10006
活跃指数 32
LU金币 2596 个
LU金条 0 个
阅读权限 200
注册 2003-11-7
 
发表于 2003-11-18 12:41  资料  个人空间  短消息  加为好友 
偶做的东西不多,但始终保持一些笔头的纪录,事实证明对偶,对别人都是有好处的。

我们公司做的项目不是很大,个人认为文档系统也不够完善,造成很多事情的延误和忽略。因此最近头头增加了GNATS, TWIKI 来加强同事间的交流。

不同的文档,在不同的阶段,对不同的人有着不同的应用。

我始终认为,人是活的,一个项目组应该根据模版,选择自己需要的,舍弃可以忽略的部分,使文档成为程序员,分析师,客户,Marketing 都能各取所需的资源库。

我们写文档,毕竟不全是为了我们自己,就像我们编程序,并不仅仅是写程序,而是要让人更便捷的使用它。

顶部
weihello
LU幼天使
Rank: 2



UID 1227
精华 1
积分 29
帖子 53
活跃指数 0
LU金币 5406 个
LU金条 0 个
阅读权限 20
注册 2003-10-31
 
发表于 2003-11-18 13:13  资料  个人空间  短消息  加为好友 
需要写文档的代码说明什么? 不可readable。 不可readable的代码是ugly code.

不可readable的代码说明什么问题?说明需要refactoring

没有意图的代码是没有的,那么代码怎么体现意图?用文档? 为什么不用测试表示意图呢?

世界上本来首先有意图,才有代码的实现。 那么,为什么不让意图也成为readable的代码呢?

readable的意图代码是什么?单元测试。


假如我是一个程序员,我接手上任给我留下来的工作,我希望看到什么?

1、一两句概要的描述该功能(或者模块)完成的功能,而不是长达N页的文档,那样令我不得要领,况且很多程序员的语言组织能力也有限。

2、测试,体现需求的测试,输入什么,应该得到什么。有测试我改起来很有自信,我不怕犯错误,改了后测试出错了,我可以立即知道就是我刚刚改的那地方出问题了。 如果我需要新增功能,那我增加测试代码(two hat)

3、可读的代码,类和接口是名词,行为是动词,每个行为的职责单一.......



我还需要什么? 不需要了。thx.





生活需要点糖

http://www.erproad.org
顶部
无双
荣誉斑竹
Rank: 14Rank: 14Rank: 14Rank: 14
天才猪



UID 4
精华 84
积分 5863
帖子 11390
活跃指数 0
LU金币 4248 个
LU金条 0 个
阅读权限 200
注册 2003-9-16
来自 杭州
 
发表于 2003-11-18 13:35  资料  个人空间  主页 短消息  加为好友 
你接手时是希望从一个一个模块去掌握这个系统

或是从整个框架上掌握这个系统

知道它的设计流程
还有原理
还有算法

这样 下次修改代码时 就可以按照它的意图去修改

如果框架都不懂
更谈不上重构了 只能全部重写 而这样代价是很大的





不要问我结果 我只研究过程与思路
无双客栈
顶部
weihello
LU幼天使
Rank: 2



UID 1227
精华 1
积分 29
帖子 53
活跃指数 0
LU金币 5406 个
LU金条 0 个
阅读权限 20
注册 2003-10-31
 
发表于 2003-11-18 15:44  资料  个人空间  短消息  加为好友 
QUOTE(无双 @ 2003-11-18 13:35:00)
你接手时是希望从一个一个模块去掌握这个系统

或是从整个框架上掌握这个系统

知道它的设计流程
还有原理
还有算法

这样 下次修改代码时 就可以按照它的意图去修改

如果框架都不懂
更谈不上重构了 只能全部重写 而这样代价是很大的



所谓框架,还不是代码? 还不是interface? 框架也是要readable


算法,有readable的代码。

所谓设计流程,我不知道你是什么意思。

另外,我也想知道,你有多少次机会让你的团队突然接手一个全新的别人开发的项目,原有成员一个都不再了?

即使一个全新的别人开发的项目,他们没有一个概要性的描述(暂且用你们的话说,文档,但在我的团队中用stroy card)嘛?

smile.gif





生活需要点糖

http://www.erproad.org
顶部
无双
荣誉斑竹
Rank: 14Rank: 14Rank: 14Rank: 14
天才猪



UID 4
精华 84
积分 5863
帖子 11390
活跃指数 0
LU金币 4248 个
LU金条 0 个
阅读权限 200
注册 2003-9-16
来自 杭州
 
发表于 2003-11-18 15:59  资料  个人空间  主页 短消息  加为好友 
框架最后当然实现为代码

不过

你可以在文档中使用其它形式表现出来
如流程图或是类图

这样更清楚 看图的效果比看代码要好懂多

算法与逻辑 是你实现这个对象的功能时是怎样实现的 里面使用了什么方法
有了文档 你并不需要从头开始看那个对象 因为你知道它的实现逻辑
可以知道改一个功能 会影响到哪里

再就是
不可能让一个团队一直做一个项目
项目交付后 原来的人会派去做其它项目
可是 如果旧项目有问题时 需要马上增加 这时使用文档就可以方便的增加功能
而不是靠个人记忆力来想应该怎样修改





不要问我结果 我只研究过程与思路
无双客栈
顶部
weihello
LU幼天使
Rank: 2



UID 1227
精华 1
积分 29
帖子 53
活跃指数 0
LU金币 5406 个
LU金条 0 个
阅读权限 20
注册 2003-10-31
 
发表于 2003-11-18 16:19  资料  个人空间  短消息  加为好友 
QUOTE(无双 @ 2003-11-18 15:59:19)
框架最后当然实现为代码

不过

你可以在文档中使用其它形式表现出来
如流程图或是类图

这样更清楚 看图的效果比看代码要好懂多

算法与逻辑 是你实现这个对象的功能时是怎样实现的 里面使用了什么方法
有了文档 你并不需要从头开始看那个对象 因为你知道它的实现逻辑
可以知道改一个功能 会影响到哪里

再就是
不可能让一个团队一直做一个项目
项目交付后 原来的人会派去做其它项目
可是 如果旧项目有问题时 需要马上增加 这时使用文档就可以方便的增加功能
而不是靠个人记忆力来想应该怎样修改

你的inferface干什么用的? 难道只是为了让计算机读懂吗? 如果是为了让人看,你的逻辑需要详细介绍嘛?

你的类大吗?方法长嘛? 如果真的大,真的长,refactoring之,只要有测试,不用担心。分解他们.......

代码都有了,你非要看类图简单,你用工具生成。

流程图? 是面向对象嘛?那是过程式的古物。如果对象交互图还比较容易让人接受。但并非所有的地方都要对象交互图。 只要你的代码足够simple.


记忆力? 我的测试和story card干什么? 还有,更为重要的一个:原有项目成员一个都不在了吗? 他们比谁都权威。





生活需要点糖

http://www.erproad.org
顶部
[广告] 记录自己的思想火花,留住每日的技术积累,尽在拥有属于自己独立域名的博客。
qinxj
技术专家
Rank: 14Rank: 14Rank: 14Rank: 14



UID 1117
精华 1
积分 166
帖子 328
活跃指数 0
LU金币 5406 个
LU金条 0 个
阅读权限 200
注册 2003-10-29
 
发表于 2003-11-18 17:20  资料  个人空间  短消息  加为好友  添加 qinxj 为MSN好友 通过MSN和 qinxj 交谈
框架跟代码的关系可以看成是类跟对象之间的关系!





合久必分、分久必和!
顶部
[广告] 记录自己的思想火花,留住每日的技术积累,尽在拥有属于自己独立域名的博客。
carol
荣誉斑竹
Rank: 14Rank: 14Rank: 14Rank: 14
幻想懒王++


UID 1859
精华 66
积分 5139
帖子 10006
活跃指数 32
LU金币 2596 个
LU金条 0 个
阅读权限 200
注册 2003-11-7
 
发表于 2003-11-18 19:36  资料  个人空间  短消息  加为好友 
转贴一封CU网友的贴子,作为论据来反驳weihello的观点:
http://www.chinaunix.net/forum/viewtopic.php?t=204811


《中国青年报》:看看印度软件人 --------------------------------------------转贴的文章

CODE

  ○他们颇有发达的大国风范,很讲究。不像我们,马马虎虎,随意性很强
  ○他们做事的风格很书面、很理论,相比之下我们就显得有些作坊气
我在工作中,接触到印度软件人和他们开发出来的软件。从整个体系架构上看,他们的作品非常清晰,按照我们的要求实现了全部功能,而且相当稳定。但是打开具体的代码一看,拖沓冗长,水平不咋样。我们自己的一些程序员就有话说了,说他们水平真低。但是!印度人能够把软件整体把握得很好,能够完成软件,并弄出相当好的设计文档。
而我们的软件人在那里琢磨数据结构、算法,琢磨细节,各干各的。界面人员还没编码就想着是Outlook式的还是VisualStudio式的界面。不管是兵还是将,都认为自己已经成了Code(编码)高手。我们对某些特定的开发工具可能是精通的,但是就是不能保证把一个软件稳当、完整地开发出来。就跟中国足球一样,单个技术还说得过去,小快灵嘛,但整体就不行了,不能互相激发,整体欠精彩。

   我们似乎缺乏具体事情具体分析的能力(或是不屑于分析,只要能显示个人技术就行),总是走一种套路。举个简单的例子:软件中需要一个列表,用来表示我们处理的事务。该类表在业务繁忙的时候将变得很大。中国人总是用双向链表,抱着《数据结构》书在那里写链表的类。而我雇的那些印度人根据情况,有时就抛弃链表,直截了当开一个大数组。为什么印度人不用链表?他们说:你们给出的设备(小型机),最少具备512M内存,占用一些没有什么。另外,数组方式访问方便、效率高。他们干事情就这么简单明了,跟哥伦布竖鸡蛋一样(怪不得哥伦布对印度那么向往,不期然发现了印第安)。各位看出了一拿到项目就吭哧吭哧做Code,和好好进行软件分析的不同了吧?

印度人不是我们想象的那样随意马虎

   正好,前几天我有几个同事从印度回来,交流后使我更加确信,印度人不是我们想象的那样随意马虎,实际他们的做法颇有发达的大国风范,很讲究。不像我们,马马虎虎,随意性很强(英国人纵有千般不好,但有一点,非常规范,这个世界的许多程序和规则都是他一家定出来的,什么格林威治时间、全球经纬、英美法、现代大工业结构……他们过去总看不起亚洲人,尤其是印度人和中国人,认为没规则,或是有规则不执行,玩undertable,即私下交易。现在印度人至少在软件业看不出这种毛病了)。
 
   请看印度那家公司给我的几点感受吧:1,流程重于项目。2,质量监察独立于研发部门,专门检查研发部门的开发流程是不是按照既定流程走。如果QC(质量管理)人觉得流程不对,他会直接上报高层,项目肯定就此停止。3,所有的材料(包括草稿)都有文档。4,准备工作做得很充分,详细文档要求达到拿到这个文档就可以编码的程度。一般写文档时间占60%,而编码时间极少。5,有各种详细的review(同行评审),项目组内的、项目组之间的、客户的……6,计划很详细,几十天的大项目竟能精确到小时级。

   一句话,中国的软件开发水平很低,赶不上印度人。甚至我们现在许多人都处在深深的自卑当中,感到中国的软件工程水平的低下已经是牵涉到“民族劣根性”的问题了。比如,印度人做事的总体风格很书面、很理论,相比之下我们就显得有些农民和作坊气,有了好的线索,我们并不跟着干,总是要看到有了试验田,而且稻子长得好,才换稻种,而在中国的软件开发水平下,又很难给你一个好的例子。要知道,这个时代,一天等于二十年,在国外,上述软件开发模式的应用,大可以看看Rational(合理的)网页上的例证,Just do it(做就是了)!
   
   我们招聘印度人,给应聘者出了一份与国内差不多的试卷,有基础概念和编程题目。等到他们完成后,我们这些自认的中国高手惊呆了!他们做的编程题目简直像是有统一答案,程序结构,注释,变量命名就不说了吧,表达方式都极其类似!反观中国的牛人、高手,每个人有自己的一套。到了新的岗位,先把前任的程序贬损一通,然后自己再开发有更多问题的代码来代替。我统计了一下我的公司,一个软件中有4个以上CSocket版本,每个人都觉得别人做得差,自己再搞一套。中国人,就是这个样子,还会辩解说“我们这样有创造性。”每个公司都上演旧时代的韬略之策

   其实软件发展,早就走过了求伯君那个编码英雄的年代,程序员已降成是个坐办公室的蓝领了,你具备拧好一个螺丝钉的能力就可以了,Code是最低级的事情了。其他国家的许多公司的项目经理根本就不懂技术。中国的项目经理如果不能在技术上压服下属,那么下属将与他搞鬼,越是高手越喜欢搞鬼,在内部搞不团结。技术高手都会纠集一些崇拜他技术的菜鸟,与管理层作对,根本不知道做软件的终极目的是从别人兜里掏钱。而印度的软件经理根本就不懂正在做的东西,许多甚至直接就是MBA,或者是领域专家(工业设计、地理专家等),而不是编码的专家。但是却能够领导大群素质良好的程序员把工作做好,没有内部不团结的情况。

   许多印度的程序员加入一个公司很长时间,都不知道自己整天编的代码是干什么用的。给他们的任务可能就是一个函数的声明以及该函数要实现的功能。我们呢?

   印度的软件公司的编程人员流动率(包括内部项目之间的流动)高达30%,他们可以让高中生编代码,可以想见他们整体的文档水平如何。他们的产品不依赖任何一个人,谁都可以立即辞职,产品的开发还会正常进行。而中国,是老板怕总工。技术骨干拥兵自重,抗拒管理。任何制定好的计划,都有可能被技术人员推翻或者跟你消极怠工。而老板物色到了可以替代的人,或是项目到了鸟尽弓藏的阶段,会想办法把已经坐大的技术骨干开了。每个公司都上演旧时代政治韬略那一套。

   如果一个印度公司的项目经理没有上班,那么他的下属将可能不知道作什么。他们的计划普遍定到天,有的定到小时。每个基层开发人员每天的工作量就是8小时。而我们能够给出月度计划的公司就很少,而给出的月度计划要么不可能实现,要么可能被取消。开发人员被粗略地给个任务,在月初,他可以慢慢琢磨是做成什么样子,然后上上网,聊聊天。到了月中和月末,就开始熬夜编码。

   中国的程序员骂微软,追Linux是全世界最狠的,可是我们除了汉化Linux,做了什么东西出来?CDE是瑞典人写的,Linux是芬兰的,GNome是墨西哥人写的。唉,我们有些人曾经是那么瞧不起印度人.


---------------------------------------------------------------------------------
观后感:我眺不起印度这个国家,因为他们吹牛比我们起码现代化10年。
但是对于印度的软件业,我一直心寸佩服。

顶部
[广告] 记录自己的思想火花,留住每日的技术积累,尽在拥有属于自己独立域名的博客。
weihello
LU幼天使
Rank: 2



UID 1227
精华 1
积分 29
帖子 53
活跃指数 0
LU金币 5406 个
LU金条 0 个
阅读权限 20
注册 2003-10-31
 
发表于 2003-11-19 09:55  资料  个人空间  短消息  加为好友 
QUOTE(carol @ 2003-11-18 19:36:51)
转贴一封CU网友的贴子,作为论据来反驳weihello的观点:

呵呵,也不必这么正式

前头我说过印度的软件工厂, 如果你是程序员,你还赞成这种做法,说明你愿意是机器,这真是悲哀。 你的欲望被阉割了。

另外,我向提醒你一句,为什么我们的程序员水平普遍差于美国的程序员? 当然,有历史、文化的原因。但我告诉你,如果再继续这样象发表这篇文章的人那样无聊的事情,我们的差距会越来越远。

奉劝一句,实实在在,勤勤恳恳,多编码,少做无聊空洞的所谓文档、设计流程这些事情。

美国人在造航母,我们要学习;印度人在造渔船,愿意学习的人就去学习吧。你相信神州五号是800月薪的民工造出来的吗?

印度人当然很多方面值得我们去学习,不过,我们要做的是,超越他们,接近和达到美国人的水平。





生活需要点糖

http://www.erproad.org
顶部
[广告] 记录自己的思想火花,留住每日的技术积累,尽在拥有属于自己独立域名的博客。
无双
荣誉斑竹
Rank: 14Rank: 14Rank: 14Rank: 14
天才猪



UID 4
精华 84
积分 5863
帖子 11390
活跃指数 0
LU金币 4248 个
LU金条 0 个
阅读权限 200
注册 2003-9-16
来自 杭州
 
发表于 2003-11-19 12:29  资料  个人空间  主页 短消息  加为好友 
偶不同意

不过这已经变成因为争论而争论了

讨论下去也没有什么意义

外国更看重的是团队精神
重要的是一个团队能做到什么
而不是一个程序员自己能做到什么

最后就是 当你发现要使用文档的时候就使用它
如果你现在觉得没有用就不使用吧
文档是一个功能 而不是一种形式





不要问我结果 我只研究过程与思路
无双客栈
顶部
weihello
LU幼天使
Rank: 2



UID 1227
精华 1
积分 29
帖子 53
活跃指数 0
LU金币 5406 个
LU金条 0 个
阅读权限 20
注册 2003-10-31
 
发表于 2003-11-19 13:43  资料  个人空间  短消息  加为好友 
QUOTE(无双 @ 2003-11-19 12:29:25)
偶不同意

不过这已经变成因为争论而争论了

讨论下去也没有什么意义

外国更看重的是团队精神
重要的是一个团队能做到什么
而不是一个程序员自己能做到什么

最后就是 当你发现要使用文档的时候就使用它
如果你现在觉得没有用就不使用吧
文档是一个功能 而不是一种形式

文档和团队不会有什么必然联系吧。
西方重视个人价值。
团队精神不能用文档联系。

团队合作和个人价值是相辅相成的。

并非为争论而争论,我的思想核心简而言之如下:

程序员是做程序的,程序员是工匠,而非艺术家、打字员或者作家,更非机器;程序员是软件开发中最重要的因素。
XP也无非是让人们公认的一些手段和方法发挥到极限:code review,test, design,simple,framework,continuous integration。这些技术术语并非XP社团专有,他们都或多或少在已有系统中体现过。尤其是软件工程。

与其说是革命,还不如说是最佳组合。 不用抗拒他,而是去理解他。





生活需要点糖

http://www.erproad.org
顶部
threehair
荣誉斑竹
Rank: 14Rank: 14Rank: 14Rank: 14


UID 27
精华 78
积分 3034
帖子 5716
活跃指数 0
LU金币 2093 个
LU金条 0 个
阅读权限 200
注册 2003-9-17
 
发表于 2003-11-22 01:35  资料  个人空间  短消息  加为好友 
看到一段很棒的话,哦觉得足以总结整个讨论:
规则是帮助你的。但是你要正确的认识他,就象你拿的文档是给你总结经验的。如果你把文档变成死的,变成压在你头上的紧箍咒,那可能就限制你的创新,你要正确理解。因为对于每个软件公司来说,规则不是外加的,是你自己建立的,你不要建立了规则去说服自己,要建立规则帮助你,如果你发现这个规则不合适了,影响创新,或者你创新需要新规则,你就得要调整规则。





╭⌒╮ ╭⌒╮╭⌒╮
╱◥███◣╭╭ ⌒╮
︱田︱田   田|
关门,上锁,钥匙已生锈。
世事静方见,人情淡始长!
顶部
 



当前时区 GMT+8, 现在时间是 2008-12-5 19:06
乐悠LoveUnix论坛-京ICP备05005823号

Thanks to Discuz!  © 2001-2007    Power by LoveUnix.net
Processed in 0.057668 second(s), 6 queries , Gzip enabled

清除 Cookies - 联系我们 - 乐悠LoveUnix - Archiver