diff options
| -rw-r--r-- | parnas-a-rational-design-process.rst | 39 |
1 files changed, 22 insertions, 17 deletions
diff --git a/parnas-a-rational-design-process.rst b/parnas-a-rational-design-process.rst index 4725a3e..8b9601c 100644 --- a/parnas-a-rational-design-process.rst +++ b/parnas-a-rational-design-process.rst @@ -325,23 +325,28 @@ Page 14 F. 编写程序 -在所有这些设计和文档编制完成后，我们已经准备好可以编写实际的可执行代码。 -我们发现这件事进展的迅速而顺利。我们认为，代码不应该包含与已经编写好的 -文档相冗余的注释。这没必要的，并且会使系统的维护更加昂贵，同时增加了代 -码与文档不一致的可能性。VI.文档在这一过程中的作用是什么？A． 当前的文 -档有什么问题？为什么它不便使用？为什么它晦涩难懂？ - -很明显，文档在我们描述的设计过程中扮演着重要的角色。大多数程序员认为文 -档是一种必要的累赘，是在事后才做的，只是因为有些官僚需要文档。但我们认 -为，在发布之前都没有使用过的文档一定是糟糕的文档。 - -大多数文档是不完整和不准确的，但这些并不是主要的问题。如果是的话，只要 -简单地添加或者纠正信息就可以纠正它们。事实上，有一些根本的组织问题才是 -导致不完整和不准确的原因，而且这难以修复： - -糟糕的组织。今天的大多数文档可以被描述为“意识流”和“执行流”。意识流写作 -将信息放在作者写作的时候突然想到的那个点上。执行流描述了系统在运行时发 -生的事情的顺序。 +在设计和文档编制完成后，我们就可以编写代码了。我们发现这件事进展的迅速 +而顺利。我们认为，代码注释不应该包含文档中已经有的内容。否则，系统维护 +会更加昂贵，同时增加了代码与文档不一致的可能性。（因为会出现注释改了， +而忘了更新对应位置的文档。或者文档改了，而忘了更新对应位置的注释。） + + +VI.文档在这一过程中的作用是什么？ +``````````````````````````````````````````````````````````````````````````````` + +A． 当前的文档有什么问题？ 为什么它不便使用？ 为什么它晦涩难懂？ + +很明显，文档在我们描述的设计过程中扮演着重要角色。大多数程序员认为文档 +是一种必要的累赘，是在事后才做的，只是因为有些官僚需要文档。但我们认为， +在发布之前都没有使用过的文档一定是糟糕的文档。 + +多数文档不完整不准确，但这并不是主要的问题。如果是的话，只要简单地添加 +或者纠正信息就可以纠正它们。事实上，有一些根本的文档组织结构问题才是导 +致不完整和不准确的原因，而且这难以修复: + +- 糟糕的组织。今天的大多数文档可以被描述为“意识流”和“执行流”。意识流写 + 作将信息放在作者写作的时候突然想到的那个点上。执行流描述了系统在运行 + 时发生的事情的顺序。 |