ライブラリの実装仕様の説明の記述方法
Closed this issue · 8 comments
コードだけで説明しきれない個所がでてきている。
（桁数の扱いの考え方など）
現時点の設計ガイドラインは、コメントを書かない。
ある程度は、書いたほうがよさそうだが、できるだけ書かないほうが望ましい。
アイデア
- クラスのJavaDocをある程度は書く
- package-info.java に、そのパッケージの基本的な考え方を書く
- 詳細な仕様（契約）は、テストコードで表現する
ライブラリは中の実装がわからなくても利用できるべきと考えるので、
テストコードでの表現は利用者に優しくない気がします。
package-infoは一つの手でですが、パッケージ内の全クラス分を書く必要が出てきそう
クラス追加でここをメンテするのもしっくりこない
ので、私は一つ目のアイデア推しです。
クラスのブロックコメント”だけ”に集約していると、利用者も深追いせずに理解できると思います。
ライブラリをいろいろな人がメンテしていくとなると、可読性やなぜそうなったのかを理解するうえで
メソッドにもコメントが欲しいのかもしれませんが・・・
ライブラリは中の実装がわからなくても利用できるべきと考えるので、
テストコードでの表現は利用者に優しくない気がします。
たしかに。
package-infoは一つの手でですが、パッケージ内の全クラス分を書く必要が出てきそう
クラス追加でここをメンテするのもしっくりこない
おっしゃるとおりですね。変更箇所が、発散してしまうのが気になる。
私も、 クラスのJavadocで補足する方針がよいと思います。
メソッドについてはガイドラインにあるように、
コメントを書かない（書かなくてもわかるメソッド名にする）方針が良いと思います。
DecimalAmountあたりで補足の書き方を実験してみましょう。
補足の書き方としては、クラスのJavadocで補足する方針でよいでしょうか？
設計ガイドライン#ドキュメンテーション に追記してもよろしいでしょうか？
はい。その方針でいきましょう。
ガイドラインの追記もよろしくお願いします。
ありがとうございます。
簡単にですが、下記の内容で直接更新しました。
ドキュメンテーション
- クラス名、パッケージ名は、javadoc 形式で「日本語」を明示する
- それ以外は、コメントを書かない。コードで説明する。
- コードだけで説明しきれない内容は、クラスのjavadocに記載する
ありがとうございます。
この issue はクローズします。