0

通常のコメントよりも javadoc/phpdoc を選択する理由と状況は何ですか? 構文の違いはわかっていますが、どちらか一方を使用する理由は何ですか。それは主にセマンティックですか、それともどちらかを使用する必要がある他の理由はありますか?それらは何ですか?

javadoc/phpdoc コメントの目的がよくわかりません。次のコード ブロックの何が問題になっていますか? .../**特定のコメントをエディターで別の色に変える方法はありますか...一部のエディターは区別しません(バニラサブライムはそうではないようです)?

/*
 * This block is wrapped in /** */ not /* */
 * Some documentation goes here
 * Below is copied from http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
 * @param  url  an absolute URL giving the base location of the image
 * @param  name the location of the image, relative to the url argument
 * @return      the image at the specified URL
 * @see         Image
 */

別の質問...同じファイルで/** */との両方を使用する必要がある理由はありますか?/* */

最後の質問... javadoc/phpdoc コメントがクラスに関連付けられているように見えるのはなぜですか?

実際にはさらに別の...私自身の質問に答える危険を冒して、javadoc/phpdocコメントは、ツールによって自動的に作成されたコメントと開発者によって作成されたコメントを区別する単なる方法なのだろうか?

4

3 に答える 3

7

人々が Javadoc を使用するすべての理由は、一貫性と読みやすさのためです。構文を知っていれば、他の人のコードを簡単に見て (またはその逆)、意味をすぐに理解できます。次のようなものではなく：

// This method is used for counting sheep just before bed time
// It's really awesome, and takes the bed-time, and also age,
// And also number of sheep, in reverse order.

処理に時間がかかります。見る方がずっといいです：

/**
 * Count the number of sheep at bedtime
 *
 * @author Tom Walters 
 *
 * @param sheep   The number of sheep to count
 * @param age     The age of the person going to bed
 * @param bedTime The time of going to bed in 24hr format
 * @return The sheep were counted successfully
 */

パラメータの数とそれぞれの目的がすぐにわかります。戻り型についても同様です。また、チームで作業するときに、作成者がそこにいると非常に便利です。そうすれば、羊が迷子になったときに誰に叫ぶべきかがわかります。

-については、/**このスタイルをランダムなコメントやオンライン コメントなどと区別するのに役立ち、コードを参照するときに Javadoc を目立たせるのに役立つ便利な規則です。

原則として、コードを書くよりも維持することになるので、このような明確に定義された構文を持つことは素晴らしい考えです。基本的な情報のためにテキストの大きなブロックを解読します。

于 2013-03-27T21:32:46.787 に答える
3

フォーム/** */は通常、ドキュメントに使用されます。したがって、クラス、ファイル、関数、クラス メソッド、クラス フィールド、または変数をドキュメント化する場合は、その形式を使用する必要があります。

フォーム/* */には、 のようなコード コメントのみが含まれます//。

一部の IDE は、ブロック内に含まれる phpDoc 情報を使用/** */してヒントを表示します。また、phpDocumentorのようなソフトウェアは、ブロックを使用/** */してドキュメント ファイルを生成します。

于 2013-03-27T21:31:22.437 に答える