6

API ドキュメント (「パブリック関数の javadoc」など) で、従来のドキュメントと同様に「値の制限」の説明をよく目にしますか?

注：コード内のコメントについて話しているのではありません

「値の制限」とは、次のことを意味します。

  • パラメーターは null 値 (または空の文字列、または...) をサポートできますか?
  • 「戻り値」はnullになる可能性がありますか、それともnullにならないことが保証されていますか（または「空」になる可能性がありますか...）？

サンプル：

私がよく目にするのは（ソースコードにアクセスできない場合）次のとおりです。

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp
 * @return array of reader names
 */
 String[] getReaderNames(final String aReaderNameRegexp);

私が見たいのは次のとおりです。

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp 
 * (can be null or empty)
 * @return array of reader names 
 * (null if Report has not yet been published, 
 *  empty array if no reader match criteria, 
 *  reader names array matching regexp, or all readers if regexp is null or empty)
 */
 String[] getReaderNames(final String aReaderNameRegexp);

私のポイントは次のとおりです。

getReaderNames() 関数を含むライブラリを使用する場合、多くの場合、その機能を推測するために API ドキュメントを読む必要さえありません。しかし、私はそれを使用する方法を確認する必要があります。

この関数を使用するときの私の唯一の懸念は、パラメーターと戻り値に関して何を期待する必要があるかということです。パラメータを安全に設定し、戻り値を安全にテストするために知っておく必要があるのはこれだけですが、API ドキュメントでそのような情報を目にすることはほとんどありません...

編集：

これは、チェックされた例外またはチェックされていない例外の使用に影響を与える可能性があります。

どう思いますか ？値制限とAPI、それらは一緒に属しますか?

4

5 に答える 5

5

それらは一緒に属することができると思いますが、必ずしも一緒に属する必要はありません。あなたのシナリオでは、生成された API ドキュメントとインテリセンス (言語/IDE がサポートしている場合) に表示されるように制限が文書化されていることは理にかなっているようです。

言語にもよると思います。たとえば、Ada には「制限された整数」であるネイティブ データ型があり、整数変数を定義して、それが特定の数値範囲内にのみ (そして常に) あることを明示的に示します。その場合、データ型自体が制限を示します。API ドキュメントと IntelliSense を介して引き続き表示および検出できるようにする必要がありますが、開発者がコメントで指定する必要はありません。

ただし、Java や C# などの言語には、このタイプの制限された整数がないため、公開ドキュメントの一部になる情報である場合、開発者はコメントで指定する必要があります。

于 2008-09-14T20:21:57.417 に答える
2

この種の境界条件は、間違いなく API に属していると思います。ただし、私はさらに一歩進んで、これらの null 値が何を意味するかを示します (そしてしばしばそうします)。例外がスローされることを示すか、境界値が渡されたときに予想される結果を説明します。

常にこれを行うことを覚えておくのは難しいですが、クラスのユーザーにとっては良いことです。メソッドが提示する契約が変更された場合（null値が許可されないように変更された場合など）、それを維持することも困難です...メソッドのセマンティクスを変更するときは、ドキュメントを更新することにも注意を払う必要があります。

于 2008-09-14T20:19:06.613 に答える
1

@ファイアーランサー: そうですね！例外について忘れていましたが、特にこのパブリック メソッドがスローする可能性のあるチェックされていない「ランタイム」例外について言及したいと思います。

@マイクストーン：

メソッドのセマンティクスを変更するときは、ドキュメントを更新することにも注意を払う必要があります。

うーん、関数のコントラクトに影響を与える変更が行われるたびに、パブリック API ドキュメントが少なくとも更新されることを願っています。そうでない場合、それらの API ドキュメントは完全に削除される可能性があります。

あなたの考えに食べ物を追加するために（そして@Scott Dormanに行きます）、Java7アノテーションの未来に出くわしました

それはどう言う意味ですか ？その特定の「境界条件」は、ドキュメントに記載するのではなく、API 自体でより適切に使用し、コンパイル時に適切な「アサート」生成コードで自動的に使用する必要があります。

そうすれば、'@CheckForNull' が API にある場合、関数の作成者はそれを文書化することさえせずに済むかもしれません! セマンティックが変更された場合、その API はその変更を反映します (たとえば、'no more @CheckForNull' など)。

この種のアプローチは、「境界条件」の文書化が必須の慣行ではなく、追加のボーナスであることを示唆しています。

ただし、関数の戻りオブジェクトの特別な値はカバーされません。そのためには、完全なドキュメントが必要です。

于 2008-09-14T20:43:42.780 に答える
1

私は彼らがそうしていると思いますし、常にヘッダーファイル (c++) にコメントを配置してきました。

有効な入力/出力/戻りコメントに加えて、どの例外が関数によってスローされる可能性があるかにも注意します (戻り値を使用して値を返すことがよくあるため、エラー コードよりも例外を好みます)。

//File:
// Should be a path to the teexture file to load, if it is not a full path (eg "c:\example.png") it will attempt to find the file usign the paths provided by the DataSearchPath list
//Return: The pointer to a Texture instance is returned, in the event of an error, an exception is thrown. When you are finished with the texture you chould call the Free() method.
//Exceptions:
//except::FileNotFound
//except::InvalidFile
//except::InvalidParams
//except::CreationFailed
Texture *GetTexture(const std::string &File);
于 2008-09-14T20:18:26.567 に答える