今回はいつもと趣向を変えて、業務の中で感じたことをまとめていきたいと思います。
現在、主にいわゆる下流工程と呼ばれるコーディング以降の工程に携わることが多いのですが、今感じたことを備忘録としてまとめて、後々上流工程に携われるようになった時に活かせればいいなと思っています。
また、皆様の意見もコメントでいただけると嬉しいです。
今回のテーマ
今回のテーマは設計書の書き方について、感じたことです。
それは、その機能が実現したいことを表現するために設計書内にコーディングするのはやめてほしい…ということです。
このような設計書に出会うとぱっと見は何も感じないのですが、コーディングを実際に進めていくと「これって害しかないのでは？」と感じるようになります。
この感覚について自分の中で深掘りして、何故そのように感じたのか、どのように設計書を作成するのが良いのかなどをまとめていきたいと思います。
背景
まず、そもそも「設計書内にコーディングする」の意味がわからないと思いますのでその説明から。
ある現場で詳細設計書内に、その機能が実現したい処理を基本設計書から抽出し、それをステップ毎に区切り、ご丁寧にそのステップのメソッド名まで指定されていました。
他の現場ではAPIの設計書でDBからデータを取得する処理を記述する箇所に、これをそのまま使ってくれと言わんばかりにSQL文が記述されていました。
このように、実際のコードで記述する内容（メソッド名など）やコーディングする際に考えるべきこと（どのようなステップで区切るか）、実際のコード（SQL文）などを設計書内に記述している状態を「設計書内にコーディングする」と表現しています。
そして、このような設計書を用いてコーディングする度に、「設計書にコーディングする」ことによって面倒ごとが増えているなと感じてきました。
何がダメだと感じたのか
では「設計書にコーディングする」ことの何がダメだと感じたのかをまとめていきます。
１．そもそも実際にその通りにコーディングすることがほとんどない
まず何より、これ。
設計書にコーディングされてもコーディングしていくうちに動かない箇所や不都合な箇所が出てきて修正することになります。
そうなると、コーディングされている部分の意味を読み取って実現したい機能を察する必要が出てきたり、コーディングと相容れなくなるため全く無視せざるを得なくなるなど余計な面倒が増えます。
これでは時間をかけて設計書を作成した人も、コーディングする際に面倒が増える人も不幸になるという残念な結果になります。
２．設計書の保守が大変になる
2つ目は保守していく際に大変になるということです。
私は実際にこのような設計書を保守した経験はないのですが、少し考えるだけで保守が大変になると想像できます。
例えば、設計書にSQLを記述している場合、もし利用するDBが変わった場合に文法が変わる箇所が出てくるでしょう。
コード上で修正するのは当然ですが、設計書上の修正も必要になってきます。
この場合、設計書にSQLではなく実現したいことだけを単に記述していれば修正の必要はなかったはずです。
また、１で言ったような理由で実装との差異が生まれた場合、実装を元に設計書を直す必要が出てきます。
設計書からコードを書くという関係が崩れてしまうのです。
こうなると設計書の完全性を保つのは難しくなりますね。
設計書が腐るのも時間の問題となってしまいます。
３．設計書としてドキュメント化する意味がなくなる
ここで一度、そもそも何故設計書を作成するのかを考えてみましょう。
コードを見れば実装されている機能が何をしているのかは読み解くことができます。
また、設計書はコードと整合性を常に保たなければ意味がありません。
つまり、コードさえあれば最低限システムは作れますし、設計書を作成し保守することはコストがかかると言うことです。
それでも、設計書を作成するには理由があります。
それは、端的にコードだけだとわかりづらいからでしょう。
設計書を作成により処理を抽象化することでその機能が何を実現しているのか、あるいは実現したいのかを素早く読み取ることができるようになるのです。
では、その設計書にコーディングされていたらどうでしょうか。
コードだとわかりづらいから作成している設計書をわざわざコードの近づけてしまっています。
それでは設計書を作成する意味が薄れてしまいます。
では、どうすれば良いのか
ここまでまとめてきて気がつきましたが、要するに設計書にどの程度の抽象度で記述するかというのが今回のテーマの本質だと思います。
「設計書にコーディングする」とは、設計書に具体的な内容を記述しすぎているということです。
設計書には本来、その機能が実現したいことを最小限で記述されているべきです。
極論を言うと、どんな言語やフレームワーク、ミドルウェアなどを選んでも同じ設計書で同じ機能が実装できるというのが設計書の理想なのではないかと思います。（現実ではそうはいかないでしょうが。）
この、最小限の記述で済ますと言う意識を持つことが、今回の問題を解決するために重要だと思います。
つまり、「誰がコーディングしても同じインプット・アウトプットになる」と言う条件を満たした最低限の抽象度の記述を心がけましょう、と言うことですね。
まとめ
今回はいつものような技術についてをまとめるのではなく、自分の考え方のような部分をまとめてみました。
あまり上手にまとめられませんでした（特に解決策のところ、抽象的すぎて何の役にも立たなさそう。。）が、自分の感じたことを言語化していくことで気づいたことも多かったのでこれからも何かあれば記事を書いていきたいと思います。
今回のテーマは「設計書内にコーディングすな！」でしたが、その本質は設計書を作成する意味とその内容に適した抽象度だと思います。
設計書とは本来、コーディングや保守を簡単にし要件からコードへの落とし込みの橋渡しとなるものですが、それを実現するためには絶妙なバランス感覚が必要になるんだなと今回まとめてて気がつきました。
自分が設計を担当する際は意識していきたいと思います。
ここまで読んでいただきありがとうございました。
それでは、また。