如今，几乎每种场合都有软件库。其中许多库设计良好且实现完善。不幸的是，几乎没有一个库的文档以允许新用户快速理解基础知识并有效地投入使用的方式呈现。
许多库使用 Doxygen 或类似的工具将其代码中的注释转换为 HTML 文档。这里的目标是解释每个函数和类是什么以及做什么。在某些情况下，这就是用户获得的全部内容。这相当于说“这是一个锤子。它用于敲钉子。这是一个钉子，它用于将木头固定在一起。”，然后期望用户能够建造房屋。对于用户学习如何根据自己的需求使用该工具而言，这根本不是正确类型的信息。
如果您幸运的话，您尝试使用的库将提供教程。教程通常解释一个类或库的某部分的基本工作原理。教程很棒，当然应该是用户学习库的整套方法的一部分，但它们有两个主要缺点。首先，创建它们非常耗时。它们通常包括大量描述性文本，每几行代码就配有图像、图表等，所有这些都需要付出巨大的努力才能制作出来。其次，教程仅涵盖单个用例。也就是说，它们演示了一个非常基本的用法，并将数十种可能的变体留给想象。
那么，如果文档和教程都不够，我建议什么呢？示例！示例和教程之间有什么区别？示例是库特定用例的快速而简单的演示。它不需要冗长的文本来描述每行代码，而只需要几句话来解释示例做什么。如何做留给读者查看代码，并参考相关的教程和文档。您可能会认为涵盖每个用例是不可能的。当然，您是对的。但是，涵盖足够多的用例，让用户能够弄清楚他们想做什么，实际上是完全可以实现的。
生成这些示例的程序非常简单 - 实际上大部分工作已经完成！关键是收集它并将其存储在易于查找、易于使用的格式中。理想的过程如下。用户遇到了他们不知道如何解决的问题。这就是将演变成示例的用例。用户通过论坛、邮件列表、IRC 频道或任何其他通信方式向社区提出问题。与其简单地问一个问题（“您如何做 XYZ？”），他们应该创建一个他们尝试过的最小示例，并解释他们的代码当前做什么，以及这与他们想要做的有什么不同。在这一点上，一个示例几乎诞生了！甚至在问题解决之前，就应该将示例添加到“愿望清单”部分中的示例集合中。贡献者绝不应该回答不在愿望清单中的问题。这样做有两件事。首先，它确保问题的提出方式将有助于未来的用户以及当前的提问者。其次，它（几乎）确保答案将被整合到问题中，为社区中的每个人留下一个漂亮、整洁、可编译的示例，供大家享用。
根据我的经验，这样做在几个方面有所帮助。提问者有时会自己解决问题，因为以这种方式提出问题迫使问题被简化为关于库的一个小的、特定部分的问题。回答问题的人已经完成了大部分工作，可以花更少的时间解释问题的解决方案。邮件列表流量显着减少，因为在一段时间内（当人们仍在学习自己使用/搜索示例时），大多数问题可以通过简单地回复示例链接来回答。最终，当人们学会自己检查示例时，大多数问题都会完全消失，所有新问题都应表明需要添加示例。最后，结果是一个惊人的示例集合，用户可以使用这些示例来学习如何做他们需要做的事情。当然，如果他们不能，那么就该添加另一个示例了！
这个过程的美妙之处在于工作是众包的。更棒的是，大众有参与其中的既得利益，因为收益直接归他们所有！
我已在多个软件库中应用了这项技术。最成功的是 VTK 示例 和 ITK 示例 。在 PCL (pointclouds.org) 中，示例现在直接添加到存储库中。我创建了一个专门用于其他库（在维护者被这个想法说服期间！）甚至编程语言本身的网站。几个 Qt 示例、C++ 示例 和 Boost 示例 可用。Boost 图形库 (BGL) 一直乐于接受，我们现在正在将 BGL 示例 移至 Boost 存储库的过程中。
您还在等什么？走出去，开始示例化吧！
9 条评论