設計書って何なの?なんで書かないとダメなの?コードだけでいいでしょ?
スクールでプログラムを勉強している、学校で習った、趣味で何か作ってる・・・そういう方々が「仕事」で何かやろうと思ったときにこんなことを疑問に思うかもしれないです。
「え?設計書なんているんですか?」「ソースコードだけでいいですよね?」「設計書なんていらないでしょ?」
でも結論から言うとほとんどのケースであった方がいいです。
「設計する」ことと「設計書」をわけて考える
設計することは絶対大事です。
紙に書かず頭の中だけでも「これをどうやって解決しようか?」「本当にこの方法でいいのか?」と設計することは大事です。ここに異論がある人はいないと思います。
設計書とはその設計をドキュメントとして書くこと(書いたもの)です。
「設計」することの大事さはおいておいて今回は「設計書」に着目します。
設計書には必ず「目的」がある
作るからには何かしら目的があります。よくある目的を説明していきます。
目的1.自分の頭の整理のため
意外とこれ多いです。
小さいプログラムなら頭の中で整理できるのですが、ちょっと大きいプログラムになると紙にメモしながらじゃないと大変です。そのメモが設計書です。
目的2.未来の自分のためのメモ(書かないとすぐ忘れるから)
人は意外と忘れっぽいです。「あれ?なんでこんなことしてるんだっけ??」というのを残すことも大事です。
もちろんこれはソースコード上にコメントで残しても良いです。
目的3.レビューや承認というコミュニケーションのため
趣味で1人で作るようなプログラムと違って、仕事で作るプログラムは関係者が多く、かつ、なるべく間違ったものを作らない方がいいです。
最後まで書き上げてから「あ、それ違うよ」と言われると手戻りが大変です。
なのでなるべく最初の方に「こんな感じで作ろうと思うのですが変なところありますかね?」と確認したいです。ソースコードだけで全体像を把握するのはちょっと難しいのでそのために設計書は便利です。
承認というのも大事です。(自分の身を守るためにも)関係者にちゃんと理解してもらって うん と言ってもらうことは大事です。
目的4.プログラムが得意じゃない関係者にレビューしてもらうため
目的3の補足ですが、レビュアーがあまりプログラムが得意じゃないケースはよくあります。
ちなみにQiita読者なら設計書は日本語が多いかなと思います。英語も多いかもしれないです。でもエスペラント語で書く人は少ないかなと思います。なんでエスペラント語が少ないかと言うと理解できる方が少ないからです。
同じ理屈で一般的にビジネスの関係者はソースコードを読むより日本語(英語)を読む方が得意なので「(日本語で書かれた)設計書」は重宝されます。
目的5.ソースコードでは表現できないことを書く場所に使う
プログラムはプログラム単体で存在しません。
必ず使う人や外部のシステムや実行する環境などがあります。
そことのつなぎ込みの部分や前提や制限などソースコードを取り巻く環境について書くことはたくさんあります。
こういうことはソースコードには書きづらく設計書が重宝します。
もちろんソースコードにコメントとして書くこともできます。読みやすいかどうかは置いておいて……その場合はソースコードが設計書になってると言ってもいいです。
目的6.納品や管理のため
仕事の内容を証明する・後世に残すためです。
だったら「ソースコードだけでもいいでしょ?」と思うかもしれないです。
「言われた通りソースコードを作るだけ」の作業ならそれでもいいです。でもエンジニアの仕事って「ソースコードを作るだけ」じゃないことがほとんです。あいまいだった要件を補完したところ、ソースコードがこういう形になった理屈理由、使い方、制限、ライセンスや法務的な注意事項・・・などなど言わないといけないことはたくさんあります。
目的7.なんとなく惰性で書いてるだけ
もちろんそんなこともあります。
書かなくていい正統な理由があるなら書くのやめちゃいましょう!
補足:読者をちゃんと想定して書く
読者を想定しましょう。
小学生?大人?エンジニア?企画?・・・日本人?英語圏の方?・・・熟練チームメンバー?新規参画者?
書くべき内容や粒度は変わってきます。
補足:書くコストも考えて書く
「明日急に会社やめるかもしれないからいつでも引き継ぎ出来るように書く」・・・会社辞める確率はどれくらいでしょう?その確率が極めて低いなら「いつでも引き継ぎできるように全てドキュメント」はちょっとコストかかりりすぎですよね。
「明日隕石が衝突して人間が絶滅するかもしれないからプログラム組みません」・・・という人がいないのと一緒です。可能性だけで考えるのではなくちゃんとコストや確率を考えましょう。
まとめ
書くためにはもちろん理由があります。
やるにしても、やめるにしても、ちゃんと理由は考えましょう!