さらに上の話題の続き

id:daxnayaたんのどの時点でJavaDocを整備すべきかから引用。

要はいつJavaDocを作るか（JavaDoc用のコメントをプログラムに埋め込むか）が問題なのだろう。開発プロセスはいろいろあるが、テストファーストという前提にして、タイミングがいくつか考えられる。

テストを書いた直後。ターゲットのメソッドシグネチャを書いた後、C-c C-v j (jde-javadoc-autodoc-at-line) でJavadocのスケルトンを生成して、今からどんなメソッドを作ろうとしているのかを書くクセをつけている。それが上に書いた、

また、Javadoc を書くことにはテスト的な意味もある。どのようなクラスを作るのか。何をするためのメソッドを作るのか。テストを書くのと同様に、Javadoc を書くことで改めて頭の中で仕様を整理できる。

という効果をもたらしてくれる(ことが多いと感じている)。
テストを書いたときって、既にそのメソッドで何をやろうとしているのか頭にあるわけよね。それをテキストにするだけのこと。でもその時点でテキストにしようとしても、往々にして、頭で考えていたことが漠然としていることを思い知らされる。
その状態でコードを書き始めてはいけない。きちんと整理する。仕様を明確にする。それこそがきっとテストファーストの目的なんだろうから。
しっかりと頭の中を整理する。整理できたら、頭の中の暗黙知をテキストという形式知に変換してやる。これだけでメソッドというコードにプログラマの意図が反映される割合は70%アップする(当社比)。