Software development of explosion! -夢の破片(カケラ)たちの日々-

ソフトウェア開発を中心としたコンピューター関連のネタを扱ったブログです

Software development is passion and explosion!

詳細設計書とJavadoc

開発言語にJavaを採用しながら、昔ながらの詳細設計書の記述(コードの日本語訳)を書いている業務系のプロジェクトが多々あると思う。
そこで思うのが、コードを2度記載しているため非効率であるのと、OOPやってると、日本語訳では記述し切れない部分が出てくる。
あくまでも持論なのだが、詳細設計書には不変な部分(開発対象の内部的な処理の流れや、入出力詳細など)を記載する程度に止めて(例えばどう言うタイミングでDBにアクセスしたり、ファイルアクセスしたり、別のサブシステムやら外部システムを呼び出したり)を記述するのと、入出力データの内容(出力メッセージだったり、ファイルフォーマットだったり)、全体的なルール(例外に対しての処理は基本的にどこどこの階層で行うため、それより下の階層では例外処理は行わないなど)を記述する程度に止めて、アルゴリズムやロジックなどの詳細は、特記事項でもない限り、Javadocに解説を記載するようにする。
何故、Javadocなのかというと、コードを修正するので、Javadocも弄るだろうから。(それに、Eclipseなどを使うと、メソッドなんかのJavadocも表示されるので、別ドキュメントを参照、修正する手間が減るから。

何が正しいとか、こうでなければならないなんてものは誰かが勝手に決めたことで、変えれば効率化出来るところは変えて行こうぜ!って言いたい。

iPhoneから送信






iPhoneから送信