1

假设您必须 [从头开始编写、重写、重构] 一个示例程序，该示例程序说明如何使用一些中间件/SDK/库或可能只是一些编程技术来做一些非常具体的事情，所有这些都是为了学习目的。

您如何记录示例程序？

我之所以这么问是因为我发现即使完全重写了一些 SDK 示例，即使有大量评论，我也觉得需要一些高级元文档或评论，或者你可以称之为的任何东西 - 一些描述什么的概述页面项目是关于。

  • 每个示例程序的README 文件都可以完成这项工作，但它们没有 wiki 的漂亮格式，例如。

    • 优点：简单
    • 缺点：过于简单；不是源文件的一部分；

  • Doxygen 评论：你认为有可能以每个项目输出一个 Doxygen 生成的“主”页面的方式编写 doxygen 评论吗？

    • 优点：部分源文件；（如果可能）有用的超链接文档主页。
    • 缺点：没有我能想到的

  • 版本控制系统 + TRAC 票务/wiki 系统：由于我的项目使用 Subversion，在我看来，将 TRAC 与 SVN 存储库一起安装可以完成记录示例程序的工作，但我不确定这是否是矫枉过正因为我没有在工作环境中使用 TRAC + Subversion，而且我不确定 TRAC + Subversion 的使用工作流程，通常写在票证、维基页面中的内容，所有这些是如何“连接”到特定修订的需要记录的程序等。

    • 除了 Subversion 存储库之外，使用 TRAC 的（可能是疯狂的）想法是否有意义？或者我完全错过了使用 SVN + TRAC 的工作流程的要点和基础知识？
    • 优点：功能丰富
    • 缺点：（也许）设置和维护的过度杀伤力
4

2 回答 2

1

我倾向于更喜欢源代码中的文档。我认为这增加了它被发现和维护的机会。在我的 Java 世界中，您可以生成相当不错的 JavaDoc，可以从源代码中提取，包括包级概述材料。

我会在那里添加解释性概述材料，或者在应用程序的主要入口点，如果我有的话，我的“主要”是。

实际上在我的源目录中的 README.txt 也将使其进入我的 SCM，这样它也可以工作，但我只是更喜欢与我的程序文档的其余部分保持某种形式的统一。

于 2009-08-30T20:56:57.037 回答
0

如果可能，请考虑最常见的场景并为每个场景提供简单（理想情况下是单独的）示例。我发现使用新的 SDK 通常非常令人沮丧，因为示例做了一两个与我的需求无关的非常具体的事情，所以我对如何开始一无所知。

至于文档，我首先要确保示例代码具有良好的干净编码风格，并且注释良好（代码内注释和 DocXml/Doxygen 函数注释都可以在编码时阅读和/或提取到外部可读格式）。这本身应该足以让优秀的程序员理解示例（即类注释应该描述如何/在哪里/为什么使用该类，而不仅仅是包含类的名称，单词之间有空格！）

然后我会添加一个快速入门指南和/或示例概述 - pdf 将是一种很好的格式，因为它允许您使用漂亮的格式并且易于阅读和打印。你是对的，概述是有用的。从您的最终用户的角度考虑：“我从未见过这个 SDK，我想做 XYZ。我应该先看哪里，我需要了解哪些关键概念？”。

要记住的主要事情是尝试使用您的 SDK 的人以前从未使用过它，因此解释不应假定任何先验知识，而应涵盖基础知识。这是大多数 SDK 文档失败的地方：作者是使用 SDK 的专家，他们的水平已经远远超出了读者的理解。或者他们会记录所有内容，因此最终用户会被关于一千个 API 调用的信息淹没，但不知道首先调用哪一个才能开始。通常，一个句子可以节省人们花费数小时/数天的时间通过示例/文档来试图弄清楚事情是如何工作的。

于 2009-08-30T21:08:03.847 回答