SUNは、「Javaクラスのドキュメント化の標準」である特別なjavadocフォーマットを考案しました。 私の練習では、一部のコードがコードレビューに合格しなかったのは完全に当たり前のことでした。一部のメソッドにはコメントがないためです。
このアプローチは時代遅れであり、今日はコメントが悪である理由を説明します。
人生の例
これは、怠けすぎず、メソッドについてコメントを書いた非常に勤勉なプログラマーによって2010年に書かれた実際のコードです。 満足しましたが、マシンからコーヒーを注いで、ここにあるものを見てみましょう。
public class AddressUtil {
/**
* Format string as address , expected input
* format:"EE ; ;Tallinn;Narva mnt;120B;831;10127"
*
* @param flatAddress
* @return Formatted address
*/
public static String toString(String flatAddress) {......}
}
いいね！ 特別なプログラムがHTMLドキュメントを生成できるjavadoc形式のコメントが正しくフォーマットされています。 それから、この方法が（理論的に）何をするかを簡単に理解できます。
悪魔はどこに隠れましたか？
しかし、悪魔が隠れたささいなことはどこにありますか？ そして、ここにあります：
- 別の開発者が来てコードを変更するので、すぐにこのドキュメントは古くなってしまいますが、ドキュメントの変更を忘れます。 同じ開発者でさえあるかもしれません。彼がコーヒーを求めて並んでいる間に、彼が1つのまれなケースを処理するのを忘れていたことがわかりました。 戻ると、必要なIFをコードに追加しますが、 サポートする必要があるjavadocが既にあることを忘れます。
- ドキュメントには多くのケースが記載されていません ：入力にnullまたは空の文字列が到着した場合、メソッドはどのように動作しますか？ 住所に家番号はあるがアパート番号はない（つまり、ブルジョアが家全体を占めている）場合はどうなりますか？ 「EE」と「Tallinn」の間の空のパラメーターは何ですか？
- ドキュメントには、このメソッドが返す単語はありません。
- ドキュメントには、「*」、「@ param flatAddress」、「@ return Formatted address」の3行が追加されています。 ただ考えてみてください：それらはほとんどのドキュメントを占めており、まったく役に立たないのです！
魔法
それでは、ウィザードをプレイして、いくつかの色のついたピースをガーランドに変えましょう。 魔法のパスを作りましょう。 Sim-salyabim、Akhalai-mahalai、Lasyaki-masya ...
- パス番号1： 赤で書かれたものはすべて、メソッド名toString-> formatAddressに変換されます。
- パス番号2： 青で書かれたものはすべてユニットテストに転送されます。
- パス番号3 ：（私のお気に入り）すべてのテキストは緑色で書かれています-...そうです、削除してください。 永遠に。 彼をspareしまないでください、彼は無駄に生まれました！
public class AddressUtil {
public static String formatAddress (String flatAddress) {......}
@Test public void testFormatAddress() {
assertEquals("Narva mnt 120B-831 10127 Tallinn",
AddressUtil.formatAddress("EE ; ;Tallinn;Narva mnt;120B;831;10127"));
}
}
新しいオプションが古いオプションより優れているのはなぜですか？
- それは愚かな短いです：8行があった、それは4になりました。
- このテストは廃止されることはありません。 プロジェクトをビルドするたびに自動的に開始され、プログラマーがコードを変更してメソッドを忘れると、すぐにポップアップします。
- 空行、パラメーターの欠落、無効な値など、すべてのまれなケースを説明できます。
一言で言えば
良い名前+テスト=ドキュメント
より具体的には、「実行可能なドキュメント」、つまり、単に読むだけでなく「実行」できるドキュメントであり、それがまだ適切であることを自動的にチェックします。
彼らは、孔子がベッドの上にポスターを掛けたと言います。
コメントを実行可能なドキュメントに変換する
あとがき
私は、キッチンから戻ってきた勇敢なプログラマーが私たちの魔法の動きを見ていないので、フォーカスを理解できないのではないかと心配しています。 タワーは、彼のコメントが「失われた何かを失う」という単なる事実によって取り壊され、彼はそのような破壊的な活動のために私たちを見つけて破壊しようとします。 その間、彼のコーヒーは冷やされました。 それは悪くありません。コーヒーは有害であると言われています。 それで、今日は良いことをしました。
更新
ドキュメントなしでオープンソースのライブラリを使用するのは不便であるという事実についてのコメントには多くのdigりがありました。 この記事はエクスポートされたコードに関するものではありません。 それは、あなたとあなたの同僚が書く「内部」コードに関するものであり、あなたとあなたの同僚だけが使用し、あなたはまだ繰り返し変更する必要はありません。 「エクスポート」コードでは、すべてが異なります。ドキュメントが必ず必要ですが、その状態は個別に監視する必要があります。 変更する必要はなく、読むだけです。 これはまったく異なる話です。
アンドレイ・ソルンツェフ