いいプログラム仕様書の残し方！
いまふと気づいたので、一筆記載します。
何十年もIT業におり、特に業務系アプリケーションやってますと、以下の現象に見舞われます。
「あれ？このプログラムなにしてんの？」
長持ちするプログラムを作りますと、自分が作ったプログラムの意味が分からなくなる。
「爺さん飯はまだかい」の状態に、たくさんプログラムを作っているとだいたいそうなります。せいぜい１年ぐらいしか覚えてないでしょう。
で、頭に思い浮かぶのは
１．概要設計書
２．詳細設計書
３．成果物（プログラム本体）
の３つにはなりますが、最近それぞれコツがあるなと分かりました。
まず、
１．概要設計書
これは、どちらかというとこのアプリが何者かということが、「素人でも初見５分以内になんとなくわかる」のが理想であり、要約、概要説明があればいいです。
料理のレシピでいうと、料理名：「たまごかけごはん」、写真だけでも十分いい感じです。
作成や更新日付
なるべく短い説明
「図示」されるもよし、画面ペタペタ貼るもよし
「人間語」
できればユーザー用途や意味
で書かれていることが重要です。
あくまでダイジェスト版であり、あとで思い出したり、お客様に聞かれたときにパッと答えられたり、他の人がぱっと見でわかるのがいいと思います。
次いで
２．詳細設計書
これは、ひと昔までは細かく書くべきでした。
しかし、最近のコンピュータ言語ソースコードはかなり英語文書のように短文で描けるようになりました。そのため、細かい仕様書はソースコードないし、ソースコードのコメント行が代用できると考えており、あまり細かく書かない方がいいと考えています。
でないと、ソースコードと詳細設計書に同内容を書くことになり、仕様変更時にソースコードは最新を追いかけますが、詳細設計書側の最新追従がよく遅れまして、内容にブレが入り、双方の最新追従がとても手間がかかります。
（特に、ドキュメント側の内容が古くなる。むしろ混乱を生みます。）
ここで必要な情報は
作成や更新日付
このプログラムを10年後に再度開発/修正するために必要な開発環境構成メモ（最近の言語はVerupが速く、同ソースコードがすぐに動かなくなるため）
このプログラムのファイル構成と各ファイルの役割、大体の意味
参照データベースがある場合、スキーマ構造、マッピング
処理内容のおおまかな順番
どういう情報が入り、どういうアウトプットがあるか
実は試験シートは、大まかなものがあると仕様書の代わりにはなります。
このレベルでいいと思います。
最後に
３．成果物（プログラム本体）
こちらが昔の詳細設計書、兼ソースコードになります。
コメントとしていろいろ書くのがいいと思います。
私もいろいろなソースコードを見てきましたが、「業務の意味」「その部分の機能の意味」「ややこしい変数の意味」「ここ危険」などをきっちりコメントを書く人はバグが少ないと思いますし、ソースコードを引き継いでも直しやすかったです。
なお、各項目に「日付」と記載しています。
人間、時がたつと何をしたのかはサッパリ忘れてしまうのですが「いつ頃それをしたことがある」ということは思い出しやすいです。
今日私は本業で、「昔、導入当初にデータ連携テストをしたけれども、当時のデータをそのまま流用したいな」を思い出すとき、何年頃に、同じようなことやったよねというのは覚えていて、過去データを拾うのが速いです。
…Git使いはなぜかタイムスタンプを軽視するのですが、タイムスタンプは「更新していない」「このファイルはもう触ってはいけない」「チェックはスルーしてよい」担保がExplorerでファイルを一見してすぐわかる、電話越しで他人相手に声で画面見なくても確認できるので、楽ができるため私は必要と思います。
※ なぜ、Gitはタイムスタンプ維持しないのか意味がさっぱり分からない。
ということで、ちょっと記載してみました。
要するに、ぱっと見で5分以内に要点が分かり、15分以内に雰囲気がわかればOK。
ご拝読ありがとうございました。
この記事が気に入ったらサポートをしてみませんか？