39:開発アーキテクチャドキュメント

プログラミング迷子: 決めた指針はどこにいった？

• 先輩T：最近、また関数名に is_ をつけるとか、他にもいくつか、決めたことが守られてないようだよ。

• 後輩W：あー、そういえば前に言われたような気もします。

• 先輩T：決めたときに、コーディング規約のページに書いたと思うんだけど、見ていない？

• 後輩W：すみません、そこは最近見てませんでした。DBやテストのページは見てたんですけど、見るページが多くて毎回全部は見れなくて……。

• 先輩T：なるほど、じゃあ1箇所にまとめようか。

開発中に決めたチームの開発ルールやベストプラクティスは、開発期間とともに増えていきます。 内容も、コーディング規約だけでなく、モジュール設計、関数引数の扱い、バリデーション方法、テーブルカラムの扱い、テストコードの書き方、Git等のブランチの扱い、リリース手順、等々、多岐にわたっていきます。

決めたルールそれぞれをカテゴリ毎にドキュメントやWikiページにまとめていき、いつでも参照できるようにするべきです。 しかし、そういったドキュメントには、具体的なコードの書き方やコマンド例、その方法を採用した経緯や哲学などが追記され、重要なポイントを押さえづらくなります。 そこで、ルールの詳細や具体例とは別に、ルールの決定事項だけをまとめたドキュメントを用意して、開発ルール全体を俯瞰して確認できるようにしましょう。

ベストプラクティス

チームの開発運用ルールを 開発アーキテクチャドキュメント に書いて、更新していきましょう。 開発アーキテクチャドキュメントはあらかじめ用意できるものではなく、プロジェクトの結果として完成していきます。 チームで合意した選択基準や開発ルールを明文化し、気分や時間経過によって起こる実装方針のぶれをなくすのが、開発アーキテクチャドキュメントの役割です。

（中略）詳細は書籍 自走プログラマー をご参照ください