11

私のチームは、大規模システム用の API の開発を担当しており、それも作成しています。API を使用している他の開発者がその使用方法を学習できるように、サンプル コードを提供する必要があります。xml ドキュメント コメントを使用してコードを文書化してきました。例えば。

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

次に、Sandcastle を使用して、必要なヘルプ ファイル (chm とオンライン Web サイト) を作成します。

サンプル コードが機能しないのは非常に恥ずかしいことですが、これは通常、一部の機能が変更されたか、単純なエラーが原因です。

誰かがこのようなことをしたことがありますが、ビルド中に動作することがわかっているように、サンプルコードで実行するように単体テストを構成しましたか?

4

4 に答える 4

9

XML で、「この場所からコード サンプルを取得してください」という特別なマークアップを使用することをお勧めします。単体テストで実行できる通常の C# ファイルを参照します。例を挙げると、次のようになります。

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

単体テストは通常​​どおり実行され、「XML の作成」と「Sandcastle の実行」の間にビルド ステップが挿入され、各「ファイル トークン」が適切なコンテンツに置き換えられます。doc 生成時にこれを行うために Sandcastle に入れることができるフックさえあるかもしれません - 私は Sandcastle について十分に知りません。

もちろん、独自のマークアップを発明するのは見苦しいですが、うまくいくはずです。

もちろん、これはコード例が簡単に単体テストできることを前提としています - 一部はそうではないかもしれません (リソースなどを扱っている場合)。少なくとも、それがコンパイルされることは知っているでしょう:)

于 2008-11-19T09:56:58.073 に答える
8

はい、サンドキャッスルはこれをサポートしており、例の正確性を維持することは素晴らしいことです。次のようにコード領域を指定できます。

   /// <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 でドキュメントを再生成しようとしたときにのみ、これに関するエラーが発生します。

于 2009-03-02T23:39:06.490 に答える
0

簡単な解決策: すべてのサンプル コード ヘッダーを含めて、それぞれのエントリ ポイントを呼び出す小さなアプリケーションを作成します。

#include "samples/sampleA.h"

void main()
{
  SomeFunction();
}

次に、これらの小さなアプリをビルドして実行した後、それらが正常に実行されたことを確認する必要があります。しかし、NightlyBuild サーバーと一緒にお泊まり会を開かなくても、コードが正常に実行されたことを確認できますか?

より良い解決策:出力をログに記録し、朝誰かに見てもらいます。

さらに良い解決策：出力をログに記録し、それまたは何かをgrepして、壊れていない限り誰も見る必要がないようにします。

最善の解決策:適切なテスト フレームワークを見つけてください。うまくいけば、壊れた場合やそのような場合に人々にメールを送信できるように、入手できるすべてのベルとホイッスルを備えたものです。私たちの場合、ベルとホイッスルを避け、代わりに、何かが壊れたときに鳴るUSB 警察のサイレンを接続しました。

于 2008-11-19T09:49:57.633 に答える
0

私はこれを自分で行ったことはありませんが、Pragmatic Programmers の本で言及されているのを見ました。私が間違っていなければ、「Nunit を使用した C# での実用的な単体テスト」という本に、この本のためにこれを行ったと書かれています。ただし、ポッドキャストの 1 つで言及されている可能性があります。

彼らは、書籍用に継続的なビルド サーバーをセットアップしたと述べました。私が間違っていなければ、彼らはラテックスまたはその他のテキストベースのマークアップを使用して本を書き、マークアップをフォーマットし、本のコードを構築および単体テストするための構築手順を持っていました。

于 2008-11-19T09:50:53.263 に答える