这里要提一句，要让代码能说话，理解“设计模式”是一项很重要的前提。

设计模式为我们提供了很多类名前缀，比如Factory、Sington、Observer，将这些名称
包含进类名中，那么看的人只要知道设计模式，通过看类名就可以知道基本的架构和运
行流程！

Robert兄说的Lucene关于信息检索这些背景信息，我觉得不是设计的问题了，是对相关
行业业务的理解和需求理解的问题。

 

  _____  

发件人: Harry Moo [mailto:mobing at gmail.com] 
发送时间: 2006年8月3日 17:24
收件人: 'python-chinese at lists.python.cn'
主题: 答复: 答复: [python-chinese] [ 谈谈设计]关于详细设计

 

要达到“足够的文档”这个标准是很难的。编写文档是项很繁重的工作，特别是在需求
经常发生变化的时候，往往做起来是吃力不讨好，成本很高。

往往一个很简单的想法，如果用嘴说很简单，但是写下来遣词造句、绘制图形都得左右
衡量。

 

所以我现在宁愿将成本投在高质量，有一定表达作用的代码上，用代码说话。

其实代码多少不是问题，要理解并不一定要一行行通读所有代码。

举个列子，我是写C++的，用VC写，一般在取C++类名的时候，我们就很讲究，有一定关
系的类，我们会在取名上体现出来，而且名称开头单词尽量一样，这样在VC的
ClassView列表中，那些相关的类都排在一起，哪些是父类、哪些是子类、哪些是容器
类，一目了然，不必一行一行的去看代码。

至于其中具体的算法，我想一般也没人会描述在文档中吧？都是要去看代码的，顶多在
代码前加上好的注释，解释算法流程。

当然，在每个Project都会附上一个Readme.txt文档，简单描述一下代码难以表达的东
西。

 

 

  _____  

发件人: python-chinese-bounces at lists.python.cn
[mailto:python-chinese-bounces at lists.python.cn] 代表 Robert Chen
发送时间: 2006年8月3日 17:12
收件人: python-chinese at lists.python.cn
主题: Re: 答复: [python-chinese] [ 谈谈设计]关于详细设计

 

所谓"代码就是最好的文档"，这种说法应该是起源于XP社群吧，之前我对这种说法也"
于吾心有戚戚焉"，现在我发现，其实不是那么回事。
"完善的注释"？"清晰的函数名"？"一目了然的类名"？怎么才算是完善的，清晰的，一
目了然的？这些完全处于代码编写者的主观判断，虽然大部分时间编写者和阅读者之间
有同样的认知，但是例外总是存在。
比如Lucene中IndexReader中居然有修改索引结构的接口，作为开源的优秀代表之一，
Lucene的代码不可谓不好吧，但是你说这个名叫"IndexReader"的类名一目了然吗？
再以Lucene为例，其中的注释非常详尽，完善。但是，假如你对信息检索毫无背景，对
所谓的索引，倒排文档......毫无概念，再完善的注释也没有意义。
当项目的源文件开始膨胀，在成百上千的文件中穿梭往返，还要不断地画图，记录流
程，甚至防止你对于一个函数名或类名的理解与代码编写者之间微妙的语义差异，这个
过程真的很痛苦。
人对于数据结构的理解能力要比函数流程的理解力强太多，当函数流程开始分叉，变
长，甚至其中还有Design Pattern之类的东西时，想从源代码中自己刨出系统的行为流
程来，我觉得是自讨苦吃。更悲惨的是，如果你只有代码可利用，想从中刨出底层的核
心数据结 构来，就更痛苦了。试着去从Lucene的源码中把Lucene的底层索引结构挖出
来，就可以亲身体会一下这种痛苦。

当然，其实我也觉得，"完善的注释"，"清晰的函数名"，"一目了然的类名"......，总
之，优秀的代码，绝对是无价之宝，但是如果没有对应的优秀的文档，其实，代码对于
接手它的程序员来说，也并不是那么很容易地就"包治百病" ：）


-- 
Robert
Python源码剖析――http://blog.donews.com/lemur/ 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.exoweb.net/pipermail/python-chinese/attachments/20060803/83cffe39/attachment.html

On 8/3/06, Harry Moo <mobing at gmail.com> wrote:
>
> 这里要提一句，要让代码能说话，理解"设计模式"是一项很重要的前提。
>
> 设计模式为我们提供了很多类名前缀，比如Factory、Sington、Observer，将这些名称包含进类名中，那么看的人只要知道设计模式，通过看类名就可以知道基本的架构和运行流程！

使用命名约定只是一种编程风格或习惯，只是希望通过名字可以猜出或理解出相应的意思。但那是对有着共同的风格的人来说的，你可以在你的团队中执行某种规范，但无法要求其它的项目也遵守相同的规范。而且代码本身的写作方式也不一定很好的表现思路。所以理解"设计模式"是有一定的局限。
>
> Robert兄说的Lucene关于信息检索这些背景信息，我觉得不是设计的问题了，是对相关行业业务的理解和需求理解的问题。
>
>
这里说的是文档，这些东西是可以写进文档中的。文档是用来描述设计的，但可能不只是设计的东西。

-- 
I like python!
My Blog: http://www.donews.net/limodou
My Django Site: http://www.djangocn.org
NewEdit Maillist: http://groups.google.com/group/NewEdit

代码有风格问题，文档也是有的，你也不可能期望其他的项目能遵守相同的文档规范。
我说的也只是局限于一个团队而已，如果一个团队能一直保持他们的风格，这就将是一
个很有效率和延续性的团队。
我们每周会有代码复审的会议，团队所有人都会参加，这对于维系和改进风格，帮助新
人融入进来都很有帮助。

文档当然重要，但是写的太多肯定是负担，也容易造成过分设计，甚至导致开发人员烦
躁、意志消沉。

其实这些都是从我的实际工作中体会的，可能只适合我以往做过的东西，并不适合所有
人。
Limodou兄也可以举举实际的例子，文档在自己开发到底起着什么样的作用。这样大家
也更容易理解一些。


-----邮件原件-----
发件人: python-chinese-bounces at lists.python.cn
[mailto:python-chinese-bounces at lists.python.cn] 代表 limodou
发送时间: 2006年8月3日 17:49
收件人: python-chinese at lists.python.cn
主题: Re: 答复: 答复: [python-chinese] [ 谈谈设计]关于详细设计

On 8/3/06, Harry Moo <mobing at gmail.com> wrote:
>
> 这里要提一句，要让代码能说话，理解"设计模式"是一项很重要的前提。
>
> 设计模式为我们提供了很多类名前缀，比如Factory、Sington、Observer，将这些名
称包含进类名中，那么看的人只要知道设计模式，通过看类名就可以知道基本的架构和
运行流程！

使用命名约定只是一种编程风格或习惯，只是希望通过名字可以猜出或理解出相应的意
思。但那是对有着共同的风格的人来说的，你可以在你的团队中执行某种规范，但无法
要求其它的项目也遵守相同的规范。而且代码本身的写作方式也不一定很好的表现思
路。所以理解"设计模式"是有一定的局限。
>
> Robert兄说的Lucene关于信息检索这些背景信息，我觉得不是设计的问题了，是对相
关行业业务的理解和需求理解的问题。
>
>
这里说的是文档，这些东西是可以写进文档中的。文档是用来描述设计的，但可能不只
是设计的东西。

-- 
I like python!
My Blog: http://www.donews.net/limodou
My Django Site: http://www.djangocn.org
NewEdit Maillist: http://groups.google.com/group/NewEdit

On 8/3/06, Harry Moo <mobing at gmail.com> wrote:
> 代码有风格问题，文档也是有的，你也不可能期望其他的项目能遵守相同的文档规范。
> 我说的也只是局限于一个团队而已，如果一个团队能一直保持他们的风格，这就将是一
> 个很有效率和延续性的团队。

格式的确是一个问题，不过也有办法解决。比如象javadoc，不按它的格式，你无法生成文档。类似的工具也是一样，只要使用相同的工具。不过，首先我们能做的先是写好文档，然后才能提到交流。首先在团队做好，才能发展到其它的团队。不过这是发展的问题。在发展之前先要理清思路，找到适合自已的方法，然后在工作中进行改进。工具的选择也是一样。当然我们这里只是讨论一些如何把文档和代码结合的好方法和好工具，也许在以前可以用得上。

> 我们每周会有代码复审的会议，团队所有人都会参加，这对于维系和改进风格，帮助新
> 人融入进来都很有帮助。
>
> 文档当然重要，但是写的太多肯定是负担，也容易造成过分设计，甚至导致开发人员烦
> 躁、意志消沉。

不过文档写得多并不表示容易造成过分设计。

>
> 其实这些都是从我的实际工作中体会的，可能只适合我以往做过的东西，并不适合所有
> 人。
> Limodou兄也可以举举实际的例子，文档在自己开发到底起着什么样的作用。这样大家
> 也更容易理解一些。
>
>
对于单位的项目，文档是硬性的任务。你所做的一些设计必须要落实到文字上，这是为了了解你都做了哪些工作，是如何做的。当然这些东西并没有与代码合在一起。正如不少人说的，文档与代码对应非常差。好在项目成员比较稳定，再加上分工明确，所以有时问问题或看代码问题不大，但是对于复杂的代码一般要理解起来是非常困难的。所以在工作中可以改进的地方还很多。

对于个人的开源项目，有些人的确感兴趣，比如
NewEdit，但由于没有详细的文档都没有深入下去。还有一些由于没有相应的英文文档，都很难推广出去。就我看到有时有人提到过我的项目，但说到我没有相应的英文文档都认为没有兴趣。还有一些对NewEdit感兴趣的老外都问过我有没有英文的文档，我说没有，于是也没有什么人研究。不是说我的东西有多好，但说明文档还是非常重要的，至少从开始让人了解的那一刻。

对于开源项目，我认为文档尤为重要，为什么？因为许多开源项目非常相似，如何让别人了解你，如何让别人更好的参与，没有好的文档无法吸引人。除非你的项目的确很优秀。有时我看一个开源项目，的确有些目前还用不上了，只是想了解一下。如果文档写得好，写得清楚，我可能就会有机会去试一试。如果没有好的文档，我可能只是看看就过去了。

不知道别人是如何认为的，我的确认为文档很重要。

-- 
I like python!
My Blog: http://www.donews.net/limodou
My Django Site: http://www.djangocn.org
NewEdit Maillist: http://groups.google.com/group/NewEdit