1

私は Java の経験が豊富なので、Java の例で説明します。次のコードが存在するとします。

interface iFoo {
    /* Do foo */
    void foo();
    /* Do bar */
    void bar();
}

class A implements iFoo {
    void foo() {};
    void bar() {};
}

class B<iFoo> {
    iFoo foo;
    B() {
        foo.foo();
        foo.bar(); 
    } 
} 

//somewhere in the code:
B b = new B<A>();

ここで、B の型パラメーターとして使用できるクラス C を実装したい場合、C は iFoo を実装する必要があることがわかります。したがって、私はそこに行き、契約による設計の慣例により、必要なすべてのドキュメントがそこにあります (どのメソッドを実装する必要があるか、署名とインラインドキュメントは何ですか.

C++ では、次のようになります (間違っていたら訂正してください)。

class A {
public:
     void foo();
     void bar();
}

template<class T>
class B {
public:
    T foo;
    B() {
        foo.foo();
        foo.bar(); 
    } 
} 

//somewhere in the code:
B *b = new B<A>();

B が T に期待することを文書化するのに最適な場所はどこですか? または、逆に、A と B があり、型パラメーターとして B に渡されるクラス C を実装したい場合、B が T に何を期待しているかを調べるにはどうすればよいでしょうか? もちろん、上記は非常に些細な例です。より大きく複雑なクラスを想像してみてください。

4

4 に答える 4

3

クラスを定義するヘッダー ファイルは、ドキュメントに最適な場所だと思います。ライブラリのユーザーは、ヘッダー ファイルを見てインターフェイスを確認します。クラスまたはテンプレート全体とパブリック メンバーの両方について、ドキュメントを見つける必要があります。

クラスまたはテンプレート全体と各パブリック メンバーの両方に、目的、前提条件、前提条件などを詳述したドキュメントが必要です。

例：

foo.h:

// The "Foo" template implements a gizmo according to Smith, Jones et al.
// A Foo<T> can be used as a drop-in replacement for the usual Zip<T>.
//
// The template parameter T must be a complete object type which is
// assignable and copyable.
template <typename T>
class Foo
{
public:
    // Reflect the template parameters
    using type = T;
    using refence = T &;

    // Constructs a Foo with a given state of being active, a given age
    // and an identifier that represents its glurgh.
    Foo(bool active, int age, char id);

    // Perform the magic act of foo.
    // It is safe to call this function multiple times concurrently.
    // Returns the number of bars.
    //
    // Intended usage:
    //
    //    Foo x(false, 10, 'a');
    //    registerGlobally(x);
    //    x.activate();
    //    return x.perform();
    //
    int perform();

private:
    // ...
};

理想的には、他の参照、マニュアル、またはチュートリアルがなければ、ユーザーはヘッダーを見るだけでクラスの使用方法を理解できる必要があります。規律があり、適切なリファレンス マニュアルを並行して維持している場合は、例がなくてもできるかもしれませんが、必要な情報 (パラメーターの意味と要件、戻り値の意味) はそこにあるはずです。

抽象基本クラスからパブリックに継承する場合、これはもちろん、基本クラスにすべてのインターフェイス ドキュメントが既に含まれていることを意味し、一般的な情報を繰り返す必要はありません。ただし、実装に関して具体的に何をするかを示す具体的なオーバーライドについて、短いコメントを残す必要があります。

特定の基本クラスから派生するなど、特定の制約を満たすテンプレート パラメーターが必要な場合は、型特性、SFINAE、およびテンプレート メタプログラミングを使用して、プログラムで強制できます。テンプレート引数の要件は、人間が読める形式で文書化する必要がありますが、そのような制約をコードに適用することは衛生上適切です。

于 2013-10-16T08:34:11.240 に答える