￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣ IT ニュース＆コラム 2013/12/ 9 通巻649号 技術版 ソフトウェアデザイン館 Sage Plaisir 21 ￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣￣ コードと冗長な詳細設計書は書くな - リーダブル・コード(16) リーダブル・コードにこだわる理由は、ドキュメントをなるべく書かない ようにすることで、情報を一元化して効率化するためと、自動テストを 通すことで信頼できる情報にするためです。 誰でもコードが書けるような詳細設計書を書くべきという主張は誤りです。 誰でもコードが書けるような情報を用意することには賛成しますが、その方法が コードに対応する冗長な詳細設計書を書くことではないのです。 一元化すれば、要求定義や設計がコロコロ変わっても受け入れやすく なりますし、矛盾が発生しなくなってメンテナンスのコストも下がります。 コンパイラーがエラーを出すことで用語の表記の揺れを防いだり、テキスト・ エディターの機能を使って用語の統一化や置き換え（リファクタリング） をしやすくすることで、 信頼できる情報がコードに出来上がるのです。 全文検索すれば、瞬時に用語の定義をコメントから知ることもできます。 何より、MS-Word のバグに悩まされることがありません。 特に矛盾が発生したとき、要求定義書＞テスト結果＞コード＞コメントや ドキュメント（ときには逆に、実現可能性＞要求定義書）のように、正しいものが すぐに判断できればいいのですが、コード＝詳細設計書 という冗長なものの間で 矛盾が発生すると、どちらが正しいかの判断が難しく、時間がかかります。 しかも、そのかかる時間に何をしているかというと、結局、要求定義書や テスト結果などを確認しているのです。 詳細設計書を書くなという意味ではありません。 なぜならコードでは表現 できないことがあるからです。それは、概要と、概要を補足する図解です。 （ここでいう概要は、コードに対する概要です。 コードが想像できるまで、 要求や手段を詳細にしたドキュメントを指します。） 逆に言えば、Doxygen などを使ってコードからドキュメントを生成した場合、 概要の情報が不足していることになります。 一覧したところで概要になりません。 コードからドキュメントを生成して、コードに対応する冗長な詳細設計書を 提出することはできますが、それだけでは必要な情報がそろっていないのです。 だから、コードだけではなくドキュメントも求められるのです。 コードから自動生成できるような粒度のフローチャートも冗長なので不要です。 必要なのは概要であって、フローチャートや図は表現方法の１つです。 つまり、概要を擬似コードで表現してもよいのです。 むしろ厳密に表現できる 情報もあります。 ドキュメントに関数名やコードの一部でも書いたら、ドキュメントの意味が ないとか、意味が分からないシンボルが出てくるのはよくないから消せ、 という主張は、トレーサビリティを捨てています。 概要からコードへの トレーサビリティがあると、コード（＝詳細設計）の理解が早まります。 営業さん力作のパワポの資料には、詳細設計へのトレーサビリティがないので、 綺麗に見えても絵空事に見えてしまうのです。 ドキュメントとコードの両方のいいとこどりをするために、ドキュメントに関数名や 変数名を積極的に書いて、ドキュメントとコードのトレーサビリティを確保する 必要があります。 詳細設計書は、設計情報の属人化防止のためという主張がありますが、 プログラミング言語を読めないプログラマーがそんなにいるのでしょうか。 読みにくいコードを書く人が、読みやすい文章を書けると思っているのでしょうか。 プログラミング言語が持っている仕様を表現する機能やスコープを明確にする 機能を使用しないで、表現したり読む方が難しいのです。 つまり、詳細設計書を 書くことよりも、読みやすいコードを書く能力を高める必要があるのです。 それは、これまで連載してきた内容によって達成できます。（あとは、 理解が難しいプログラミング言語の機能を極力使わないようにコーディングする 技術の習得が必要です。） 詳細設計書がなくて、何を元にコーディングして、何を元にテストするのか、 という主張がありますが、リーダブル・コードであれば、それは、 詳細設計書やテスト仕様書を何を元に作成しているのか、という質問と同じに なります。 詳細設計書がないとできない？ 本当ですか？となるわけです。 コードは詳細設計の一部なので、要求定義書や基本仕様書を元にいきなりコーディング を始めることができるのです。 テスト・プログラムは、仕様書と、テストに求められる 要求の定義書を元に作成するのです。 もし、要求定義書や基本仕様書があいまいなときは、 詳細設計書が必要になります。 しかし、その詳細度はプログラマーのスキルに依存します。 属人化です。 しかし、コーディングが済めば、コードという詳細設計資料があり、 トレーサビリティを確保しておけば、属人化はなくなります。 残るのは、 コードが読みやすいかどうかだけです。 テスト・プログラムは、基本仕様書と、テストに求められる品質の定義書を元に作成します。 具体的なテスト・データは変換プログラムにかけられる形式にしなければ、 必ずミスが発生します。 また、テスト・データの妥当性を検証するために表形式に 変換したり、別の妥当性検証プログラムを通す必要があるかもしれません。 検証の自動化（産業革命）が必要なのです。 コードと冗長な詳細設計書を書くということは、機械が正確にできることを、 わざわざミスをする人間が行うという愚かな行為にあたるのです。 経験の浅い開発者へ実装を依頼するときに必要なのは、詳細設計書では ありません。 応用のきくサンプル・コードが必要なのです。 同じパターンが きくものを、すべての設計要素に対して人が適用することは明らかに無駄です。 コードと冗長な詳細設計書があれば、それは分かりやすいでしょう。 しかし、 そのような詳細設計書を作って維持することがどれだけコストがかかるのか 理解していないのです。 必要なのはパターンを適用できるような能力を得るための 教育の資料であり、その場所を示すことです。 最も必要な教育は、 grep（全文検索）ツールなどを使ってコードからリバース・エンジニアリング して概要を自分で理解する方法かも知れません。 他の人に引き継ぐときも同じです。 設計情報だけでなくパターンや思想や 調べ方も提供した方が引継ぎは効率的にになります。 そのためにも普段から パターンや思想（の名前）を明示しておく必要があります。 基本仕様書から生成できるものとしてレビュー（ダブルチェック）すべきことは、 基本仕様書の内容が正しく伝わっているかどうかです。 それを確認するには、 基本仕様の内容の種類によって、詳細設計書、コード、ブラック・ボックス・ テストの手順書、テスト・コード、テスト・データのどれかになります。 基本仕様書の次は詳細設計書だけではないのです。 基本仕様に内包的定義があれば、設計仕様書かコード、外延的定義があれば、 テスト系を開発してレビューします。 MECE を満たすには、要求→手段と、手段→実装の対応表（対応ツリー）を作成して、 トレーサビリティを確保することです。 詳細かどうかは主観的なものです。 また、基本設計の「基本」の意味も主観的な ものです。 また、法律上、請負は直接指示はできません。 いかに品質よく開発しているかの説明が求められたら、それらを踏まえて 効率よく対処しましょう。 参考： アジャイルソフトウェア開発宣言 http://agilemanifesto.org/iso/ja/ 詳細設計書という名のゴミ http://gm7add9.wordpress.com/2012/11/30/%E8%A9%B3%E7%B4%B0%E8%A8%AD%E8%A8%88%E6%9B%B8/ 詳細設計書のネガティブな側面 http://wwolf.web.fc2.com/file/98.html 詳細設計書が滅亡しない理由 http://d.hatena.ne.jp/kagamihoge/20100220/1266624446 そもそもＵＭＬだと、「詳細設計書」は、書かなくないか？ http://blog.goo.ne.jp/xmldtp/e/147b230c186e8b5a3d5092cb0c50ecf9 注目ニュース 一覧 ◇ 表裏気にせずに挿せるUSBの新コネクタ Type-C 規格が策定。 http://pc.watch.impress.co.jp/docs/news/20131205_626485.html … まだ何も決まっていない。 ◇ クリエイティブ・コモンズ・ライセンス4.0登場。 http://news.mynavi.jp/news/2013/11/29/054/index.html https://creativecommons.org/weblog/entry/40768 http://creativecommons.org/choose/ … 条文を改良。体系の大枠は今までと同じ。 ◇ サンタ追跡、グーグルがサイト公開。NORADはMSと2013年も連携。 http://japan.cnet.com/news/society/35040953/ … MSはイブの日に、タッチ対応機種で3D地球儀で確認する予定。 ◇ 高性能CPU戦争からAMDが脱落、Intelの一人勝ちで終焉へ 。 http://buzzap.jp/news/20131204-amd-cpu-end/ … CPU と GPU と統合した APU に集中。 ◇ Win 8.1タブレットが人気爆発、レノボ Miix 2 が即日完売で早くも品薄に。 http://akiba-pc.watch.impress.co.jp/docs/news/news/20131206_626690.html … ミニ・タブレットは、MS Office が安く提供され、4万円台に。 ◇ Windows 7、延長サポートは2020年1月14日まで。製品版はすでに販売を終了。 http://japan.cnet.com/sp/allaboutms/35041048/ … Windows 8.1 から Windows 7 へのダウンロード権もある。 ◇ ソフトウェア特許の判断基準が求められる訴訟、米最高裁へ。 http://japan.cnet.com/news/business/35041046/ … アメリカでもソフトウェアが特許にあたるか争われている。 ◇ ウェアラブル端末の正体。 http://www.itmedia.co.jp/enterprise/articles/1312/02/news037.html … 監視にも使われる。 ◇ Xbox One レビュー。リビングの中心に置く次世代エンターテイメントシステム。 http://japan.cnet.com/news/commentary/35040749/3/ … ソーシャルネットワーク機能が弱い。 ソフトウェアデザイン館 Sage Plaisir 21 ホームページ >>> http://www.sage-p.com/ メルマガ >>> http://www.mag2.com/m/0000083983.html ブログ >>> http://blog.livedoor.jp/sage_p/ ツイッター >>> http://twitter.com/Ts_Neko ダウンロード >>> http://www.sage-p.com/freesoft.htm サポート掲示板 >>> http://www.sage-p.com/kg_ban09/z6037C8.cgi 東日本大震災 >>> http://www.sage-p.com/saigai.html メール >>> ts-neko◇sage-p.com ←◇を@に変えてください 緊急メールは件名に「うどんメール」を付けてください。 このメルマガの登録・解除 - http://www.mag2.com/m/0000083983.htm