web-dev-qa-db-ja.com

コード用のJavadocを作成しないのは間違いですか。

私は多くのJavaプログラミング(私のインターンです)でプログラミングをしており、コードに付随するjavadocを作成するのが一般的なルールかどうか疑問に思っていました。通常、すべてのメソッドととにかくクラスですが、Javadocの構文(パーサーがhtmlを生成できるように変数と出力を書き留める)に準拠するのは難しいと思います。

私は多くのCプログラミング、さらにはC++を見てきましたが、それらのコメントの仕方が気に入っています。私のコードでjavadocを提供しないのは間違っていますか?

7
n0pe

どんな書き方でも、あなたは聴衆のために書きます。あなたの聴衆はメンテナンス開発者であり、あなたはそれがどのように機能するかの詳細を忘れてから3年後にあなたかもしれません。

使い捨てのコードは捨てられるので、コメントを減らすことができます。他の開発者が使用するAPIについては、さらに文書化する必要があります。

メソッドシグネチャを繰り返すだけのjavadocは誰にも必要ありません(たとえば、これはvoidの戻り値とHelloWorldの名前を持つメソッドであり、パラメーターなしで呼び出されます)。

25
MatthewMartin

これは通常、チーム/会社の決定です。正解も不正解もありません。

また、開発中のソフトウェアの種類にも適用されます。外部的に露出されて消費されるのに対し、内部的に露出されて消費される。

コメントあり;それらを有用にします。メソッドシグネチャを逆流させないでください。

7
Aaron McIver

コードにjavadocを提供しないのは間違っていますか?

はい。 意味のある javadocを作成しないのは間違いです。

意味がなく、情報がない定型的なjavadocを書くのは間違っています。

5
S.Lott

Javadocは、ドキュメント化の標準としてほぼ受け入れられていますJavaコード。HTMLに変換できることは、利点の1つにすぎません。さらに重要なことは、すべての主要なJava IDEもそれを理解しており、コーディング中に状況依存ヘルプを表示するために使用します。javadoc構文に準拠していない場合、これは機能せず、コードでの作業が非常に煩わしくなります。この便利な機能に慣れている人(特にJavaの世界では、単純なテキストエディターではなくIDEでコーディングするのが標準です)。

つまり、独自のコメントスタイルを使用することは、利己的で頑固で子供っぽいものです。 javadocについて学んでください。それはそれほど難しくなく、あなたの将来のキャリアにとっても有益かもしれません。

5
tdammers

問題がjavadoc構文に準拠するのが難しいと感じる場合は、適切なIDEが役立ちます。たとえば、Eclipseで、/ **を入力してコメントを開き、@とコード補完を入力します機能は利用可能な注釈をリストします。

結果の確認は、メソッド名の上にマウスポインターを置くだけの簡単なものです。これにより、ドキュメントリポジトリを表示するためにWebブラウザーに切り替えることなく、ドキュメントをすばやく簡単に検索することもできます。

2
Foozilla

あなたが開発したコードが、目前の状況について明確かつ理解できる形で文書化されていることを確認しないのは間違いだと思います。それが意味することは状況です。

インターンとして、あなたが書くすべてのコードは他の誰かの責任になると考えてください。これは、理解可能な文書を構成するものの前提条件を引き上げます。

特にjavadocに関しては、それはあなたとあなたの雇用者次第ですが、他の人が使用するために何かが取り残されることを確実に確認する必要があります。

2
asfallows

JavaDocはコードを使いやすくします。コードのバグ修正や変更に関しては、通常のコメントよりも役立つとは思えませんが、他のプロジェクトでクラスを使用する方がはるかに簡単であり、JavaDocコメントによって他のプログラマがクラスやメソッドを見つけて使用できるようになると、より可能性が高くなります。一般に、コードの再利用はホイールを再発明するよりも優れているため、JavaDocの省略は、コードが非常に悪いために再利用がどうしても選択肢にならない限り、ほとんど受け入れられません。

0
user281377