为什么没有开源项目的代码概述？[关闭]

那里有非常复杂的开源项目，我想我可以为其中的一些项目做出一些贡献，我希望我能做出一些贡献，但是进入的门槛太高了，原因有一个：在同一时间更改一行代码大型项目，您必须了解所有内容。

您不需要阅读所有代码（即使您阅读，也不够用）并了解每一行的内容以及原因，因为代码可能是模块化和分区化的，所以有适当的抽象，但是即使如此，你需要获得一个概述该项目，这样你就可以知道哪里是模块，其中确实有另外一个模块接口，究竟各模块做的，为什么，以及其中的目录和文件均对这些事情的发生。

我称此代码概述为开放源代码项目可以在网站或文档中向外部人员解释其代码的部分的名称。我认为这将使潜在的贡献者受益，因为他们将能够确定他们可以建立的地方，所涉及的实际主要编码人员，因为他们将能够在编写所有内容的同时重组他们的思想，并会像他们那样帮助用户。帮助理解并更好地报告他们遇到的错误，甚至可能成为贡献者。

但是我仍然从未见过这些“代码概述”之一。为什么？是否有类似的事情，我想念他们？与我描述的功能相同的事情？还是这是一个完全无用的想法，因为除我之外，每个人都可以轻松理解具有数千行代码的项目？

因为创建和维护这样的文档需要额外的精力，而且太多的人不了解相关的好处。

许多程序员不是优秀的技术作家（尽管很多）。他们很少严格地为人类食用而写文件，因此他们没有实践并且不喜欢这样做。编写代码概述需要花费您不花时间进行编码的时间，并且如果您可以说“我们支持所有三种编码变体”而不是“我们对代码的解释很整洁”，那么项目的初始收益总是更大。这样的文档将吸引更多开发人员，从长远来看，将编写更多代码的想法对他们而言并不完全陌生，但被认为是不确定的赌博；这段文字是否真的会给阻挠合作者带来不同？如果我现在继续编码， 把事情做好。

代码概述文档还可以使人感到防御。在没有感觉到需要证明其合理性的情况下很难描述更高层次的决策，而且很多时候人们做出决策时都没有理由说实际上写得足够好。还有一种与上述功能有关的效果：由于更新文本以适应不断变化的代码会导致额外的工作量，因此这可能会阻止对代码进行大范围的更改。有时，这种稳定性是件好事，但是如果代码确实确实需要中级重写，那么它将变成一种负担。

枯燥无味的真理？

没有文档，因为项目可以没有它。

甚至开源项目也经常面临激烈的竞争。大多数此类项目不是从一个大肩膀开始的，而是从一个聪明的主意开始的，通常是一个人的聪明的主意。

因此，即使他们愿意免费合作，他们也无法负担聘请人类记录员的时间和成本。实际上，一个有文档记录的项目通常首先经历了几个开始的迭代。它通常以1-3开始，也许是5个人写下了他们的新想法并将其展示给全世界作为概念证明。如果这个想法被证明是好的，那么“追随者”可能会增加，他们倾向于开始要求扩展，新选项，翻译...此时，代码仍是原型，通常带有硬编码的选项和消息。

并非所有开源项目都超出了这个阶段，只有那些打破“临界质量”以吸引公众利益的项目。而且，开始的开发人员之一必须“大胆思考”并计划扩展。他可能会成为项目的“传播者”，有时甚至成为“项目经理”（其他时候则是不同的人）。从概念验证到行业确定的现实，这是启动项目的必要步骤。

即使这样，项目经理也可能选择不创建文档。

一个动态的，不断增长的项目将被放慢速度，而文档则实际上会落后于代码，而对其进行真正的增强则很难实现翻译，选项，插件管理器...

通常发生的是：

1. 制作了一个简短的介绍性文件，介绍了项目的内容以及项目的去向（著名的“路线图”）。
2. 如果可能，将开发一种API，并在大部分基础代码中将其选为“文档代码”。
3. 特别是对API以及其他代码进行了重新格式化，并添加了“ PHPdoc” /“ Javadoc”等。添加了特殊注释。它们在花费的时间和报酬之间提供了不错的折衷：即使是谦虚的程序员通常也知道如何编写一个描述其功能的衬里，参数也被“自动”记录在案，并且整个过程都与相关代码绑定在一起，因此他们避免了记录“异步”和落后的行为。
4. 通常，创建论坛。这是一个功能强大的社交媒体，最终用户和程序员可以互相交谈（以及在同级之间，可能在“仅devs”子论坛中）。这使得很多知识可以慢慢出现，并通过社区制定的方式得到巩固（阅读：不影响开发团队）常见问题解答和HOWTO。
5. 在非常大的项目中，还会生成一个Wiki。我之所以说“大型项目”，是因为它们通常是那些拥有足够追随者的人，可以创建一个Wiki（开发人员可以这样做），然后将其实际填充到“裸露的骨头”之外（社区可以这样做）。

您所描述的概述文档即使在商业项目中也很少见。他们需要付出额外的努力，而对开发人员却毫无价值。此外，开发人员倾向于除非确实需要，否则不编写文档。有些项目很幸运，他们拥有精通技术写作的成员，因此拥有良好的用户文档。开发人员文档（如果存在）不太可能进行更新以反映代码更改。

任何组织良好的项目都将具有相对不言自明的目录树。一些项目将记录此层次结构和/或选择该层次结构的原因。许多项目遵循相对标准的代码布局，因此，如果您理解一个代码布局，则将了解使用相同布局的其他项目的布局。

要更改一行代码，您需要对周围的代码有一定的了解。您完全不必为了理解整个代码库而这样做。如果您对中断的功能类型有一个合理的了解，通常可以相当快速地浏览目录层次结构。

要更改一行代码，您需要了解找到该行的方法。如果您了解该方法的预期行为，则应该能够进行更正性更改或功能扩展。

对于提供范围的语言，您可以重构私有作用域方法。在这种情况下，您可能需要更改调用方以及重构方法。这需要对代码库有更广泛但仍然有限的理解。

请参阅我的文章“ 将SHA-2添加到tinyca”中有关如何进行此类更改的示例。我对用于生成接口的代码的了解非常有限。

是否有类似的事情，我想念他们？与我描述的功能相同的事情？

有一本非常好的书，叫做《开源应用程序的体系结构》，详细描述了各种高调的开源软件项目。但是，我不确定它是否能完全满足您的想象，因为我相信它的主要受众是打算在创建自己的应用程序时遵循模式的开发人员，而不是本书中所涉及项目的新贡献者（尽管我确信在那里可能会有所帮助）。

因为开放源代码程序员比开放源代码技术作家要多得多。

文档需要维护和时间才能保持最新。文档越庞大，花费的时间就越多。与代码不同步的文档比没用的文档更糟糕：它误导和隐藏而不是揭示。

记录良好的代码库比记录较少的代码库要好，但是只要首先编写代码，记录文件就很容易。因此，您的问题是，拥有一个记录良好的代码库或两倍大的代码库会更好吗？每当代码更改值得它可能带来或可能不会带来额外开发人员的贡献时，保持文档最新状态的成本吗？

运输代码胜出。减少交付代码以外的工作量可以使代码更频繁地发布，并且更有可能在资源耗尽之前进行发布。

这并不意味着运输以外的事情都重要。文档为该项目增加了价值，并且对于一个足够大的项目，添加另一个开发人员的互连成本可能远高于添加文档开发人员的互连成本。而且，如前所述，文档可以增加对项目的投资（通过使新程序员更容易加入）。

但是，没有什么能像成功一样卖出东西：一个无法正常工作或做任何有趣的项目也很少会吸引开发人员。

代码库的文档是一种元工作形式。您可以花费大量时间来编写描述不起任何价值的代码库的精美文档，也可以花费时间来编写代码库的使用者想要的东西并使代码库具有价值。

有时使事情变得更艰难会使做任务的人做得更好。是由于对项目的承诺程度更高（花费数小时学习体系结构），还是由于技能偏见（如果您已经是相关技术的专家，那么赶上进度会更快，因此缺乏障碍此类文档的重要性不那么重要：因此，更多的专家加入了该团队，而初学者则更少。

最后，由于上述原因，当前的开发人员很可能是代码库方面的专家。编写此类文档并不能帮助他们过多地了解代码库，因为他们已经掌握了知识，只能帮助其他开发人员。大部分开放源代码开发都是基于开发人员用代码“痒”的原因：缺乏说明开发人员很少发痒的文档。

除了付出额外的努力之外，一些开源项目还故意破坏其文档，以便为其维护人员获得自由职业（执行某些任务或进行培训）。他们不仅没有代码概述，而且他们的API和教程很糟糕，或者缺少很多东西。

仅举一个很受欢迎的名字：bluez。祝您找到一个好的教程，祝您好运，然后再扫描附近的设备。