你如何记录样本程序？

Question

假设你必须[从头开始编写，重写，重构]一个示例程序，说明如何使用某些中间件/ SDK /库做一些非常具体的事情，或者只是一些编程技术，所有这些都是出于学习目的。< / p>

您如何记录示例程序？

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

每个示例程序的

• 自述文件都可以完成这项工作，但是它们没有漂亮的wiki格式，例如。

  • 优点：简单
  • 缺点：太简单了;不属于源文件;

• Doxygen评论：您是否认为可以以每个项目输出Doxygen生成的“主要”页面的方式编写doxygen评论

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

• 版本控制系统+ TRAC票务/维基系统：由于我在项目中使用Subversion，在我看来，安装TRAC和SVN repo可以完成记录样本的工作程序，但我不确定这是否是一种矫枉过正，因为我没有在工作环境中使用TRAC + Subversion，而且我不确定使用TRAC + Subversion的工作流程，通常写在故障单中， wikipages，所有这些是如何“连接”到需要记录的程序的特定修订等。

  • 除了Subversion repo之外，使用TRAC的（可能是疯狂的）想法是否有意义？或者我完全忽略了使用SVN + TRAC的工作流程的基本点和基础知识？
  • 优点：功能丰富
  • 缺点 :(可能）设置和维护过度

Answer 1

我倾向于选择源代码中的文档。我认为这增加了它被发现和维持的机会。在我的Java世界中，您可以生成非常好的JavaDoc，可以从源代码中提取，包括包级概述材料。

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

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

Answer 2

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

关于文档，我首先要确保示例代码具有良好的清晰编码风格，并且评论良好（代码内注释和DocXml / Doxygen函数注释，可以在编码和/或提取时读取）外部可读格式）。这本身应该足以让一个优秀的程序员理解样本（即类注释应该描述如何/在何处/为什么使用类，而不仅仅包含类之间带有空格的类的名称！）

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

要记住的主要事情是，尝试使用SDK 的人之前从未使用过，所以解释不应该假设任何先验知识，应该涵盖基础知识。这就是大多数SDK文档失败的地方：作者是使用SDK的专家，他们在一定程度上超越了读者的理解。或者他们记录了所有内容，因此最终用户被淹没了有关一千个API调用的信息，但不知道首先要调用哪一个才能开始。通常一句话可以节省一些人花费数小时/天的时间通过样本/文档试图找出工作原理。