Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationEventAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
4
Help us understand the problem. What are the problem?

More than 3 years have passed since last update.

@moke039

ドキュメントやモデルに書くこと

ドキュメントやモデルに書くこと

by moke039
1 / 9

ソースがドキュメントだ。バグも完全に記述されている。 

よし!じゃあやっぱりドキュメントもモデルもソースコードの劣化コピーだからいらないね
ってなるはずなのに、なんか違和感がある……。
だからソースコードになにが書かれているかを5W1Hで考えてみた。


How どうやって

レジスタ1とレジスタ2の加算結果を、メモリのxxx番地に格納して、
メモリxxx番地の値と比較して xxx ならプログラムカウンタを
xxx に飛ばして……。

How はすべてソースコードにすべてもれなく記載されている。だから How をドキュメントに記載する必要はない。
ドキュメントには本質的な部分だけを記述するよう、オッカムの剃刀でどんどん切り落としてほしい。:barber::scissors::knife:
ただ、トレーサビリティのために必要な部分まで削ぎ落とし過ぎないように。:paperclip::paperclip:


What なにを / Why なぜ

レジスタ1とレジスタ2の加算結果を、メモリのxxx番地に格納して、
メモリxxx番地の値と比較して xxx ならプログラムカウンタを
xxx に飛ばして……。

って 結局なにがしたいの?
ソースコードはマシンが理解できるように詳細に書かれているが詳細すぎてそれが なにをするもの なのか 何のためのもの なのかが読み取れなくなっていることが多い。

トップダウンで記述するならCODE COMPLETE 9章PseudocodeProgramingProsess。なにをやりたいかをコメント文、自然言語でソースコードっぽく記載する方法。


ボトムアップで記述するなら USDM スペックアウト。そのソースコードはなにをするものなのか、なにを満たすのか、なぜそのような要求があり、そのような仕様になっているかを記載する。

関数や変数の名前付けにこだわることでソースコードだけでも表現することは可能だ。 :star::star::star:
限界があるとしたらコメント文でもいい。
またコミットコメントにはHowではなくWhat/Whyを残すようにしよう。


Who 誰が どのモジュールが / Where どこが どのぐらいの範囲で

ここから先は図や表などを用いないと表現しづらいかもしれないなー。

先のUSDMでも紹介されているトレーサビリティマトリクスや、クラス図、アクティビティ図でどのモジュールがどんな責務を担っているかが見渡せるだろう。そしてある仕様を変更した場合にどこのモジュールをどのぐらいの範囲に渡って変更しなければならないかが見えることで、より良い設計、テスト・実装が進められるだろう。

細部の一つ一つがすべて記載されたソースコードを見るよりも、スケッチとして全体像を写し取った UML のありがたみを感じられるはず。
マーチン・ファウラーさんもスケッチとしてのUMLについて以下のように述べている。

私はUMLをスケッチとして使用します。UMLによるスケッチは、
フォワードエンジニアリングとリバースエンジニアリングのどちらにも使え、
概念的観念とソフトウェア的観点のどちらにとっても便利だと思います。

When いつ、どのような順序で、どのぐらいの期間

ソースコードをエントリーポイントから読み解いて行けば、処理順序は確かに読み解ける。
でもコールバック関数が呼び出されるタイミングや、メモリなどのリソースの生存期間、競合期間は、ソースコードからは読み取りづらい。
アクティビティ図、シーケンス図を使うと、これらを容易に読み解くことができる。

ただ初学者がよく書きたがるシーケンス図はソースコードを見ればわかることしか記載されていないものがある。そんなシーケンス図が嫌いだ。
シーケンス図は、モジュール遷移のトリガーとなるメソッドを際立たせたり、クリティカルなタイミングのリソース生存期間、競合期間などを記載できるのが良いところで、逐次処理していくだけのものを記載するだけであれば、ソースコードを見るほうが有益なはずだ。


トップダウン/ボトムアップ 合理主義、経験主義 選択的無知

実践からの学びはボトムアップ、帰納的だが、それを説明するにはトップダウンで演繹的に説明するほうが伝わりやすい。
コーディング、テストを通じて得た学びをモデル図にフィードバックしよう。モデル図を見ながらよりシンプルなシステム構成を探ろう。
ソフトウェア開発は選択的無知で日々成長している。コードの詳細は知らなくても、やりたいことができる。そんなソフトウェアシステムを構築していくには、よく読んで、よく書いて、よく推敲して、システムとスキルを磨き上げよう。

ドキュメントやモデルには苦しんだ経験を明日の誰かのために書く :stars:


最後に

書きながら、うろ覚えの書籍を読み返したりしているうちに、なんかツッコミどころが満載な気がして自信がなくなってくるけど、いったん公開してみる。🎉
がっさり改定しないとだめかもだけど。🙂

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
4
Help us understand the problem. What are the problem?