architecture.面对

如果您维护的开源项目的代码行数在1万至20万行之间，强烈建议您在“自述文件和贡献”旁边添加一个ARCHITECTURE文档。在详细介绍原因和方式之前，我想强调一下并不是另一个“文档不错，写更多文档”的建议。我对文档相当草率，例如，我经常只使用“简化”作为提交信息。尽管如此，我对这个问题还是有很强烈的看法困扰着你：-)

我在开发和维护开源项目方面都有经验，我学到的教训之一是，偶尔的贡献者和核心开发人员之间的最大区别在于对项目物理架构的了解。如果您不熟悉该项目，则需要花费2倍的时间来编写补丁，但是要花出10倍的时间才能确定应更改代码的位置。如果您一直在为某个项目工作，那么可能很难理解这种差异。如果我是代码基础的新手，我会按照伪随机顺序指定的逻辑块序列读取每个文件。如果我以前做出过重要贡献，则感觉会大不相同。代码在我的脑海中，所以我不再按顺序阅读，相反，我只是跳到应该去的地方，如果不在那儿，我就将其移动。思维导图是真理的源头。

我发现ARCHITECTURE文件是弥补这种差距的一种省力的高杠杆方式，顾名思义，该文件应描述项目的高级体系结构，请简短地说：每个经常出现的贡献者都必须阅读它。此外，它越短，将来被更改所导致的可能性就越小。这是ARCHITECTURE的主要经验法则-仅指定不太可能经常更改的内容。请勿尝试使其与代码保持同步。而是每年重新访问几次。

首先概述要解决的问题，然后指定或多或少的详细代码图。描述粗粒度的模块以及它们之间的关系。代码图应回答“ X在哪里？”。它还应回答“我正在看的东西做什么？”。避免深入了解每个模块的工作原理，将其放入单独的文档或（更好的）内联文档中。Codemap是一个国家/地区的地图，而不是它的状态图地图集。以此为契机来反映项目结构。您想要在exa -TD相邻的代码图中将彼此放置在一起的内容吗？

请为重要的文件，模块和类型命名，不要直接链接它们（链接会陈旧），而是鼓励读者使用符号搜索来按名称查找所提到的实体，这不需要维护，将有助于发现相关的类似名称的事物。

显式地调用体系结构不变式。重要的不变式通常表示为不存在某些东西，很难通过阅读代码来区分它们。模型层中的任何内容都不完全依赖于视图。

还要指出层与系统之间的边界。边界隐式包含有关其背后系统实现的信息。它甚至限制了所有可能的实现。但是仅通过随机查看代码来找到边界是很难的-好边界是零。 。