Question

我的团队负责为我们编写的大型系统开发API。我们需要提供示例代码，以便使用我们的API的其他开发人员可以学习如何使用它。我们一直在使用xml文档注释来记录代码。例如

/// <summary>Summary here</summary>
/// <example>Here is an example  <code>example code here</code> </example>
public void SomeFunction()

然后我们使用Sandcastle并构建我们需要的帮助文件（chm和在线网站）。

当示例代码不起作用时，这是非常尴尬的，这通常是因为某些功能已经改变或是一个简单的错误。

有没有人做过这样的事情，还配置了单元测试来运行示例代码，以便知道它们在构建期间可以工作？

Answer 1

我建议在XML中使用一个特殊的标记，即“从这个地方获取代码示例”。它将引用一个普通的C＃文件，它可以通过单元测试运行。举个例子，你可能有：

/// <summary>Summary here</summary>
/// <example>Here is an example
/// <code>!!sourcefile:SomeClassTest.cs#SomeFunction!!</code></example>
public void SomeFunction()

您的单元测试正常运行，然后在“创建XML”和“运行Sandcastle”之间插入构建步骤，您将用适当的内容替换每个“文件令牌”。甚至可能会有一些钩子你可以投入Sandcastle在doc生成时这样做 - 我不太了解Sandcastle肯定知道。

当然发明自己的标记很难看，但它应该有用。

当然，这假设代码示例很容易进行单元测试 - 有些可能不是（如果他们正在处理资源等）。至少你知道它编译虽然：）

Answer 2

是的，sandcastle支持这一点，并且很好地保持示例的正确性。你可以指向这样的代码区域：

   /// <summary>
   /// Gizmo which can act as client or server.
   /// </summary>
   /// <example>
   /// The following example shows how to use the gizmo as a client:
   /// <code lang="cs"
   ///    source="..\gizmo.unittests\TestGizmo.cs"
   ///    region="GizmoClientSample"/>
   /// </example>
   public class Gizmo

然后，您可以在TestGizmo.cs中使用一些测试代码作为示例，将其封闭在一个区域中：

[Test]
public GizmoCanActAsClient()
{
   #region GizmoClientSample
   Gizmo gizmo = new Gizmo();
   gizmo.ActAsClient();
   #endregion
}

警告：如果您移动或重命名测试文件，当您尝试使用sandcastle重新生成文档时，只会出现相关错误。

Answer 3

简单解决方案： 制作一个小应用程序，其中包含所有示例代码标题，然后调用各自的入口点

#include "samples/sampleA.h"

void main()
{
  SomeFunction();
}

然后在您构建运行这些小应用程序后，您需要确保它们运行正常。但是，如果没有人与NightlyBuild服务器进行睡眠聚会，您能否验证代码是否正常运行？

更好的解决方案：记录输出，让某人在早上看一下。

更好的解决方案：记录输出并grep它或其他东西，除非它被破坏，否则没有人必须看它。

最佳解决方案：找到一个合适的测试框架，希望能够获得所有花哨的东西，以便它可以通过电子邮件发送给人们，如果它破碎或类似的东西。在我们的情况下，我们避免使用铃声和口哨，而是连接了一个 USB警笛，当有什么东西坏掉时它就会消失它非常令人兴奋！

Answer 4

我自己没有这样做，但我在实用程序员的书中看到了这一点。如果我没有弄错，那本书“用Nunit C＃中的语用单元测试”提到他们为这本书做了这个。可能是他们在其中一个播客中提到过。

他们提到他们为自己的书籍设置了一个连续的构建服务器。如果我没弄错的话，他们会使用乳胶或其他基于文本的标记来编写他们的书籍，他们已经构建了在书中格式化标记和构建单元测试代码的步骤。

自动单元测试示例代码

4 个答案: