开源项目里加个详细的设计文档是不是更好？

现在很多开源项目，除了代码，就只有使用文档，但极少有能具体说明其设计思想，问题解决思路的，这极大的增加了代码阅读的顺畅度。

像咱们在公司，也是要写各种文档的，有些比较负责任的程序员就会详细说明其代码使用了什么设计模式，用了何种架构等等，就算没有，我们在交接的时候也会问，对方也会如实回答。可是开源项目要是每个人都去问作者一遍为什么这么设计，那作者肯定是回答不过来。而现实是我们如果真有要需要，就只能一点一点的去啃代码，最终靠自己去补充这些设计思想和解决思路，并且我们也不会把这些结果贡献到这个开源项目里。

在我看来，现在很多开源项目其实只是披着技术分享的外衣在营销产品罢了。对于那些真正热爱技术，想要从中学习的人来说，这虽然不是问题，但是如果真有这么一份设计文档，我相信最终会有更多人受益，能大大减少阅读代码的时间。

当然我知道文档也不是那么好写的，而且随着代码的变更，文档也是要跟着做修改的，这会大大增加项目的开发成本。但我想你都开源了，这个大家不是可以共同承担吗？即使作者不这么做，那些真正参与到项目的人，本地里也或多或少会总结一些文档，只是没共享出来而已，这不是在做重复的事？个人觉得是因为作者本人懒导致，因为我就是这样的人。

有些人可能会说，这样可以锻炼个人解决问题的能力。通过阅读代码，总结出其设计思想和解决思路可以获得更深刻的理解。我不否认这种说法，但这真的很耗费时间。尤其是像 MySQL 这种大型开源项目，你觉得你能看得完？现在大家都是看书学的 MySQL 实现原理，要是由开发的人自己写这份设计文档，我相信会更好。

像我自己之前做了一个浏览器扩展，其中就用到了很多技术，很值得分享。但考虑到商业风险，我放弃了开源的想法。现在这个扩展没什么人用，我觉得已经没什么商业价值了，可以开源。但是如果只是这么简单的把代码丢上去，我觉得这就是在敷衍，因为本质上我还是想让更多人使用这款产品，然后我就可以放广告去赚点广告费了。如果加上一份详细的设计文档，会花费我大量时间，我懒得这么做。而且我更关注的是前面说的赚钱而非技术提升，因为我是做后端的，这个项目全部用的是前端，对我来说技能提升有限。而且我发这么一份帖子，也是考虑到其能对我的这款产品起到推广效果我才发。自从做了这么一款产品，我变成了一个现实的人，却也因此更加看透了这个世界。在程序员这个纯洁的世界中，我不打算披着虚假的外衣，所以说了这么一段真实的话。

我知道我这么发出来肯定会被很多人吐槽，没关系，我已经准备好迎接各位的炮火了。

cwcc

2022-03-02 13:18:35 +08:00

我感觉这个应该不是吐槽的问题，而是开源本身的定义问题。

现在大多数开源项目其实只是开源协议+代码部分开源，好一些的开源项目带 Issue 光速处理的。但是开源项目本身不是一个产品化或标准化的流程，写设计文档这件事就相当于招标投标那些流程然后开发时候做的穿插的一件事情了。如果将设计文档写好，那么开发者完全可以将这个当做一份完整的产品售卖，不开源的效益会更好。

而且设计文档本身可能写起来比代码更费力，就好比大学毕业设计写一个系统，自己写的代码是什么样心里很清楚也许没那么复杂，但就是难以在短时间内写出优美的设计方案来。

举一个简单的例子：编写一个 Web 框架，有一个路由解析函数，代码层面也许就是几个方法组合起来带过，自己心里很清楚，但是转换成详细设计文档，你就需要用额外的精力去画这个解析过程的流程图、思维导图、数据结构相关的表等，而有这些时间，我相信开发者更乐意先把 TODO 搞完。虽然一边写代码一边画流程也不是不行，但是代码可能好改，流程图也必须跟着反映变化，而这时你的思路就必须以设计文档为准了，这里你写的可能不是项目，更像是软件工程。

我觉得改善这种设计文档缺失的局面有几种解决办法：

- 首先就是让自己的项目变得成为类似标准一样的东西，自然有人会请求读源代码、看看“教科书”式的项目是怎么样炼成的。
- 其次就是不要单人开发，最好有一个不超过 5 人的小开发团队，提前对项目做好规划，但是团队内每个人都要非常清楚自己在做的事（人数少就是为了防止有人浑水摸鱼啥也不知道）。
- 开源项目模块化，尽量将自己的一个超大型项目拆分成可独立的小项目，比如会话模块、路由模块、连接保持模块等。
- 如果是小项目，可以在写 README 时，让 README 本身不仅做简介，还做一下对程序工作流程的简介（这个很重要，有时虽然可能缺失文档，但是非常有助于包括自己在内的他人可以更方便地读源代码）。

baobao1270

2022-03-02 13:51:38 +08:00

我一直有一个观点，开源是一个非常奢侈的慈善行为。你不能要求那些仅仅是凭着一腔热情、只是想分享自己业余时间做出来的好东西的人，花费大把的时间去写文档。

开源其实有两个层次，一种是普通人“我做了一个好东西、我想分享出来”的开源。即使他只是把代码 push 到 GitHub 上、没有任何说明文档也没有更新，我们也不应该指责他什么。当然，也有不少公司或者大型开源项目是这么做的。

更加深层次的开源，是完全践行开源理念的开源。有成体系的社区、严谨的贡献者协议、完善的文档，自然也会有阐述设计思路、开发方法、甚至是讲述项目历史的文档。但是这需要时间和成本，只有少数的项目能做到这一点。

如果强制要求每个人的开源都是尽善尽美的开源，那么可能很多人就会选择不开源。