Javadoc を作成する際のベスト プラクティスについて疑問に思っています。多くのファイルを含むプロジェクトがあります。コードは多くの開発者によって作成されています。各ファイルには注釈が付いている@authorため、誰が特定のクラスを作成したかは明らかです。
しかし、他の開発者がファイルに新しいコードを追加したり、変更したりした場合、新しい関数を作成したことや既存のコードを変更したことをチームの他のメンバーにどのように通知すればよいでしょうか? 言い換えれば、「Javadoc を現実と互換性を保つ」にはどうすればよいのでしょうか。;)
@authorタグに追加しますか? そうすれば、疑問が生じた場合に誰に質問すればよいかを特定しやすくなります。@author各新しいメソッド、内部クラスなどにタグを追加しますか?もちろん、SVN を使っているので、誰が何を作ったのかを調べるのは簡単ですが、物事を明確にするために、この Javadoc のことも考慮する必要があります。
@authorこれらのタグを使用する最良の方法は何ですか?
@authorほとんどの場合、不要なノイズだと思います。あなたの API のユーザーは、誰がどの部分を書いたかを気にするべきではなく、おそらく気にも留めません。
そして、すでに述べたように、SVN はこの情報をコードよりもはるかに信頼できる方法で保持しています。したがって、私がチームの 1 人だった場合、常に SVN のログを優先し、@author. どのようなポリシーを採用したとしても、コードは現実と同期しなくなるに違いありません。Don't Repeat Yourself の原則に従って、この情報を 2 つの場所に保持するのはなぜですか?
ただし、この情報をコードに含める必要がある官僚的またはポリシー上の理由がある場合は、@authorチェックイン時にコード内のタグを自動的に更新することを検討しましたか? おそらくSVNフックでこれを達成できます。たとえば、特定のファイルを変更したすべての開発者を変更した順にリストできます。または誰がそれを最も変更したか。または何でも。または、@author外部にリリースする (ソース) コードで が義務付けられている場合@authorは、リリース ビルドの一部として を自動的に追加することを検討できます (SVN からこの情報を何らかの方法で取得できると思います)。
複数のクラス レベルの@authorタグ (またはその他のコメント) を追加することに関しては、役に立たないノイズがたくさん蓄積されていると思います。(繰り返しますが、SVN があります。)
私の経験では、歴史的な変更 (コード行やメソッドの変更など) を特定し、それがどの変更セットに関連しているか (およびどのトラック チケット) を特定する方がはるかに便利です。次に、変更の完全なコンテキストを取得します。チケット、変更セットがあり、同じチケットで他の変更セットを見つけることができます。またはほぼ同時に、関連するチケットを見つけることができ、すべての変更を確認できます。その作業単位を形成しました。コード内の注釈やコメントからこれを取得することは決してありません。
それは 2021 年であり、この質問に回答しているときは、最初の公開からほぼ 8 年になります。世界は少し違う場所で、マイクロサービスをフルスロットルで使用しています。したがって、著者に関する全体的な雰囲気を次のように要約します。いくつかの点で説明しましょう。
したがって、単純なコードの編集と適切な行の変更に関する知識は、クラス全体の知識よりも重要です。
これは、短い記事にまとめられたクラスの作成者に関する私の意見です。