私たちは皆(面倒なときは!)インターフェースにコメントしていると思います。例えば
/// <summary>
/// Foo Interface
/// </summary>
public interface Foo
{
/// <summary>
/// Will 'bar'
/// </summary>
/// <param name="wibble">Wibble factor</param>
void Bar(string wibble);
}
実装にもコメントしますか (これは、たとえば、ライブラリの一部としてクライアントにも提供される場合があります)? その場合、2 つを同期させるにはどうすればよいですか? または、「ドキュメントについてはインターフェースを参照してください」というコメントを追加するだけですか?
ベストアンサー1
一般的なルールとして、私はコードと同じ DRY (Don't Repeat Yourself) 原則を使用します。
- インターフェースについては、インターフェースを文書化する
- 実装時には実装の詳細を文書化する
Java 固有: 実装を文書化するときは、{@inheritDoc} タグを使用してインターフェースから javadoc を「含める」必要があります。
詳細については:
- 公式Javadocドキュメント
- 非公式のアドバイス。