跳转到内容

包括原则

此文档既包含对 Vitium 项目所实现的全部功能需求的描述,也包含对项目的开发流程标准,与编码过程中采取的具体实现细节的记录。我们如此设计文档是为了同时保证项目的使用者能够了解功能与查阅参考手册,而开发者可以方便地在需求和实现之间进行对照。这样,面向内部和外部的文档可以被部署到同一站点上,且更加内聚,易于维护。

任何 应被外部感知的 Vitium 功能需求都应当记录在此文档内。我们现在仍有一些已在过去实现,但尚未被记录的功能。我们正在工作以补充这些文档。新实现的需求应当在合并时已经被记录。

TODO

并非全部对代码实现的记录或解释都应当收录在此文档内。我们并不打算用此文档来代替代码中的文档注释。相反,我们希望此文档能够存放那些同时影响 Vitium 项目的多个组成部分,因而难以在单个代码文件中完整记录,并易于查阅的代码实现细节。

一个典型的例子是网络通讯的协议标准:这是 Vitium 项目自身的实现细节,对外部而言无需关心,而因为同时影响服务端与客户端,在一侧代码的文档注释难以完全覆盖我们的需求。

我们鼓励在文档中不仅记录有关 Vitium 设计和实现的内容,而进一步包括对我们之所以作出这些选择和工作的目的的解释。

  • 例如,我们解释提出这一条建议的目的,是为了帮助我们记忆和还原在过去作出设计时的思考过程,从而在可能的需要重构,或开发类似功能等情景下,能够更好地理解现状并综合思考,而没有欠考虑到方面,也为我们作出类似决策提供支持。