Riccardo
撰写的评论
让我补充我的 2.0e-2 分的看法。
非常非常笼统地说（您的体验可能因人而异），我发现在一些 OS 项目中最缺少的是对软件结构的高级视图。通常，您会在 /doc 目录中找到一组自动生成的 *.html 文件，其中包含类的继承图和函数的原型。这是 <em>过于详细的</em> 文档。如果您是一位经验丰富的开发人员，那么有一些东西可以提醒您 Audio_Bugaboo 继承自 Multimedia_Bugaboo，而 Multimedia_Bugaboo 又继承自 Abstract_Bugaboo，这可能很有用，但是对于一个不知道 Bugaboo 是 _什么_ 以及它应该做什么的新手来说，一个粗略的框图，显示 Bugaboo 在哪里出现可能更有用。
我想看到一些文档的另一个地方（也是我通常放置文档的地方）是在 *.h 文件中（实际上是在 *.ads 文件中。我使用 Ada...）。在我看来，开发人员是您的 .c 文件实现的小模块的 _用户_，而放置使用模块的说明的最佳位置是 .h 文件。但是，通常你在里面找到的，例如 multibugaboo.h，是一个类似于这样的单行注释
<code>
/* multibugaboo.h: Multibugaboo 实现 */
</code>
呃... 真的吗！？这是一个惊喜...
Multibugaboo 到底是什么？！它的职责是什么？！！？此模块提供什么样的函数/过程/数据结构？！顺便说一句，没有必要详细描述 multibugaboo 的内部细节（如果真的需要，请将它们放在 .c 文件中），只需一个非常高级的描述就足够了，这样如果我正在搜索格式化数据包并通过网络发送数据包的代码，我就知道我是否在正确的文件中。
[[ 抱歉发牢骚了... 请想象一下旁边有很多微笑 :-) :-) :-) 我在写作时面带微笑，但是电子媒介不携带这种侧面信息。 ]]
所以，底线是，高级文档是新手经常需要的。矛盾的是，记录最细微的细节可能不是那么重要，它们可以从写得很好的代码中推断出来。此外，如果实现细节发生变化，但注释没有变化，则可能会引起问题。
最后，让我告诉您我对这个问题的个人方法。为了实践我所宣扬的，我发现保留一个 wiki（仅由我自己编辑）作为想法的记事本很有用。wiki 为您提供了一种轻松保持笔记井井有条的方法，并且速度足够快，不会干扰您的思路。最后，经过适当改进的 wiki 应该成为高级概述的良好基础。此外，扫描的手绘图片可以很好地用作图表和稍后用一些绘图软件生成的东西的占位符。当然，您的体验可能因人而异...
“这意味着你可以花很多时间与编译器争论，但是一旦你的程序编译通过，它就很有可能是正确的。”
如果你想要相同的体验，但是在命令式上下文中，请切换到 Ada。我已经使用它相当长一段时间了，我可以肯定地说，如果你利用这门语言提供的工具，你得到的代码将很好地抵御错误（当前和未来的错误）。
我从未使用过 Haskell，但我认识一些喜欢并同时使用 Ada 和 Haskell 的程序员。