Javadoc @authorタグのグッドプラクティス
Javadocsを作成するときのベストプラクティスについて疑問に思っています。多くのファイルを含むプロジェクトがあります。コードは多くの開発者によって作成されています。各ファイルには@authorという注釈が付いているため、誰が特定のクラスを作成したかは明らかです。
しかし、他の開発者がファイルに新しいコードを追加したり、変更したりする場合、新しい関数を作成したか、既存のコードを変更したことをチームの他のメンバーにどのように知らせる必要がありますか？言い換えれば、どのように「Javadocを現実と互換性を保つ」べきでしょうか？ ;）
- 既存の
@authorタグに彼の名前を追加しますか？そうすれば、疑問がある場合に誰に尋ねるかを特定するのが簡単になります。 @authorタグを各新しいメソッド、内部クラスなどに追加しますか？
もちろん、SVNを使用しているため、誰が何を作成したかを簡単に調査できますが、物事を明確にするために、このJavadocの内容も考慮する必要があります。
これらの@authorタグを使用する最良の方法は何ですか？
ほとんどの目的で@authorは不要なノイズです。 APIのユーザーは、誰がどの部分を書いたかを気にかけたり、知りたがったりするべきではありません。
また、既に述べたように、SVNはこの情報をコードよりもはるかに信頼できる方法で保持しています。私がチームの一員だった場合、私は常にSVNのログを好み、@author。どのようなポリシーを採用しても、コードは現実と同期しなくなると思います。自分自身を繰り返さないという原則に従って、なぜこの情報を2つの場所に保持するのですか？
ただし、この情報をコードに含める必要があるという官僚的またはポリシー上の理由がある場合は、@authorチェックイン時のコード内のタグ？ おそらく SVNフックでこれを達成できます。たとえば、特定のファイルを変更したすべての開発者を、変更した順にリストすることができます。または誰が最も変更したか。または何でも。または、@authorは外部ソースにリリースする（ソース）コードで義務付けられています。@authorリリースビルドの一部として自動的に（何らかの形でSVNからこの情報を取得できると思われます）。
複数のクラスレベルを追加する場合は@authorタグ（またはその他のコメント）、多くの役に立たないノイズを蓄積していると思います。 （繰り返しますが、SVNがあります。）
私の経験では、履歴の変更（コード行やメソッドの変更など）を特定し、これがどの変更セットに関連するか（およびチケットを追跡するか）を判断する方がはるかに便利です。次に、変更の完全なコンテキストを取得します：チケット、変更セット、同じチケットで、またはほぼ同時期に他の変更セットを見つけることができ、関連チケットを見つけることができ、すべての変更を見ることができますその作業単位を形成しました。コードの注釈やコメントからこれを取得することはありません。
ソースに著者タグが必要なwhyを検討することもできます。 Apache Foundationはそうではなく、私も同意します。
http://www.theinquirer.net/inquirer/news/1037207/Apache-enforces-the-removal-of-author-tags
私の知る限り、これはソースが紙に印刷されたときからの貨物のカルト的な作業方法です。とにかく、最新のバージョン管理システムでは、この情報やその他の情報が履歴にあります。
複数の@authorタグを使用できます。クラスに大きな変更を加える場合は、独自の名前で新しい@authorタグを追加するだけです。変更履歴に明確に表示できるため、行った変更をマークしたり、変更を名前で囲む必要はありません。
多くの開発者がいる本当に大きくて長時間実行されるプロジェクトでは、hoが特定のコードを担当していることを知っておくと便利です。その場合、@ authorタグを使用してそのような情報をファイルに含めると便利です。ファイルの作成者や主要な貢献者をマークするのではなく、そのコードの連絡先をマークします。原作者はすでに別のプロジェクトに参加しているか、数年前に退職したため、それらは非常に異なる人々かもしれません。
巨大なプロジェクトでは、このアプローチは便利かもしれませんが、注意点があります。膨大な量のファイルがあり、遅かれ早かれ失敗するため、すべてのファイルの作成者情報を保持することは非常に困難です。ますます多くのファイルに古い情報が含まれ、開発者はこの@authorを情報源として信頼せず、無視します。
動作する可能性のある解決策は、すべての単一ファイルに@authorを保持するのではなく、モジュール（高レベルパッケージ）ごとにのみ保持することです。 Javadocには、ファイルだけでなくパッケージ全体を文書化できる機能があります（ 詳細についてはこの質問を参照 ）。
ただし、これは特別なケースであり、プロジェクトがそれほど大きくも古いものでもない限り、著者情報を省略することをお勧めします。
これは不要であり、おそらく追加しないでください。それでも私はそれを追加しますが、絵画に署名を追加したり、 コンピューターの金属片のスタンプに追加したりするように見えます設計を助けました 。そのコードを書き、名前を追加すると、それを誇りに思っており、他に何もしなくてもその品質に自信があることがわかります。将来変更された場合でも、その上に構築されたすべての基盤を構築し、本当に完全に書き換えられた場合、タグを変更、削除、または拡張できます。バージョン管理のおかげで冗長であることに同意しますが、バージョン管理にあなたの名前を入れることは、ほとんど満足のいくものではありません。誰かが「最終」を追加したりコードをフォーマットしたりすると、たとえほとんど貢献していなくても、その名前はバージョン管理されます。また、コードに何も追加しないという点でノイズであることに同意しますが、実際にはわずかに目立って迷惑ですか？そうは思いません。あなたがそれについて合理的であれば、それが理にかなっているなら、プロジェクトを「より友好的」にすることができると思います。
@authorタグと複数の作成者がいると非常に便利です。 Oracleのドキュメントでさえ、@ authorをクラスの最上位に置いて、仕事をした特定の著者にクレジットを与え、開発プロセス中に誰かと話す必要がある場合に物事を追跡することをお勧めします。複数の著者がいる場合、特定のJavaファイル/クラスに貢献した順序でリストすることができます。はい、プラグインがあり、git構造では、著者名がぶらぶらしているのを確認できます。複数の作成者が同じコード行を編集し、同じコード行を編集している2人の作成者を表示しない場合があるため、プラグインを有効にしているため、同じ行を編集するために2人の作成者名が表示されることはありません大企業では、このプラクティスを設定しておくと便利です。
会社コードの場合、私はそうしません。VCSがあります。代わりに、それが私の個人的なレポのブログ投稿またはコードスニペットである場合、私は誇らしげにこれを追加します。
ちょうど私のタイプのユーモアだと思う。