Doc commentに@authorは書くべきか？

Question

ドキュメントコメントに@authorは必要でしょうか？

私の会社では30名程度のエンジニアがサービス開発に関わっています。
慣習として、クラスやメソッドを新たに作成した際には自分の名前を@authorに書くようにしているのですが、別のエンジニアが修正を重ねていくうちに当初とは全く違う内容になっていたりするので寧ろ邪魔に思えます。

皆さんの組織ではどのようにされているか、教えて頂きたいです。

Answer 1

ドキュメンテーションコメントは単に履歴のためのコメントでは無い、と考えています。
そして、@authorは、API製品、特にオープンソースの製品でJavadocをAPIドキュメントとして公開するような場合につけるもので、そうでない製品の場合はあまり重視しないと思います。

そもそも@authorを含むタグは、「いつ」「誰が」という情報をまとめて書く機能がありません。
そう考えると、履歴として@authorを適切に使う方法は正しいとは思えません。
コードの性質にもよりますが、単に最初の作成者を記録することに意味はあるでしょうか。

それに、業務ロジックなんかだと、仕様変更でいろんな人が書き手になるので、誰が書いたのかというのは割とどうでも良くなる気がします。
私の場合は、VCSのコミットに記録されたコミット者の情報を見れば誰がどういうコードを書いたのか分かりますから、そちらを見るようにします。

他にも、何か特殊なプログラムで、ほとんど仕様変更が入らず、この人が書いたというのが分かった方が良さそうな場合は、つけても良いかも知れません。

Comments

[suitedJK]

ご回答頂きありがとうございます。
私自身も全く同じように捉えておりました。
古い慣習は捨て去り、編集履歴はVCSを利用するように提案してみたいと思います。