エンジニアのためのJavadoc再入門講座

今のプロジェクトは、成果物として「プログラム設計書」なるものが定義されています。

その設計書に意味があるのならもちろん書くべきなんだけど、単に時間の無駄であるならば当然省きたいわけで。

そんなわけで、僕達のチームでは、「プログラム設計書は全部Javadocで代替します」と言い張って逃げてみました。

と言っては見たものの、実際今目の前にあるJavadocはとてもじゃないけど、後から見る人に対して胸をはって「設計書です！」とは言えない代物なわけで。。

やっぱり事前のルール作りが足りなかったことを反省して、次に活かすべくこんな本を買ってみました。

いまやJavadocの書き方で一冊本が出る時代なんだね。よく書いたな。

中身はJavadocに書くべきこと、書くべきではないことがツラツラと。
具体例が少ないのが残念。もっと良い例、悪い例をたくさん載せて欲しかったというのが本音。

ただ、考え方はとってもまっとうなので、この本もプロジェクトが始まる前に、って言うか、実装が始まる前に実装者全員で読み合わせでもしときたいなー。

サマッたドキュメントを作っておけばいいんだろうけど。作るか。

変数名を日本語にしただけのドキュメンテーションコメントは、もうまっぴらです。