【備忘録】目的がわからなかったドキュメント

はじめに

案件に参加すると、プログラムを書く以外にも、さまざまな作業が発生します。

• SQLのステップ数の確認
• 障害管理表の更新
• データマートの要件とのすり合わせ（結合テスト）

PMに言われるがままにやってはいたものの、

なんでこれやってるんだろう？
記帳に何の意味があるのか。

という気持ちがずっとありました。

この記事では、当時つまずいたポイントをベースに、「なぜ必要なのか」を整理します。

目次

1. SQLのステップ数の確認
2. 障害管理表の更新
3. データマートの要件とのすり合わせ（結合テスト）

1. SQLのステップ数はなぜ確認するのか

これが一番「意味わからない」と思っていました。

実際、SQLは正しく結果が返ってくれば、それで目的は達成しているように見えます。

そもそもステップ数ってなにかわからないし、、

でも調べてみると、目的、内容はシンプルでした。

ステップ数とは、
SQLやプログラムの「量」を数値で表したもの

目的は、

• 規模を把握するため
• 見積もりやレビュー量を決めるため

つまり、どれくらいの作業量かを測るための指標です。

例えば、

• 数行の簡単なSQL修正
• 複数テーブルを結合する複雑なSQLの新規作成

では、必要なレビュー時間やテスト量が全く違います。

これを感覚だけで判断すると、

• レビューが足りない
• テストが不足する
• 見積もりがズレる

といった問題が起きやすくなります。

そこで、ステップ数という「ある程度の基準」を使って、規模を見える化します。

ただし重要なのは、ステップ数はあくまで目安であって、品質そのものではないという点です。

例えば、次のSQLは1行ですが非常に危険です。

DELETE FROM orders;

WHERE句がないため、全データが削除されます。

逆に、長いSQLでも、意図が明確で安全に書かれていれば問題ありません。

つまり、SQLのステップ数は、

品質を測るものではなく、作業量や影響範囲を把握するための指標

として使われています。

2. 障害管理表はなぜ必要なのか

これも最初はただの作業に見えていました。

「バグ見つけたら直せばいいじゃん」と思っていましたし、わざわざ表に書く意味が分かりませんでした。

でも実際にプロジェクトが進むと、障害管理表がないとかなり混乱します。

例えば、

• 誰が対応するか分からない
• 修正済みかどうか分からない
• 同じバグが何度も報告される
• 修正したはずなのに再発する

といった状態になります。

特に人数が増えるほど、「誰が何をやっているか」が見えなくなります。

障害管理表は、それを整理するためのものです。

また、書き方も重要で、単に「バグがある」と書くだけでは意味がありません。

最低限、次の3つを分けて書く必要があります。

• 何が起きたか（事象）
• なぜ起きたか（原因）
• どう直したか（対応）

例えば、

• 事象：特定の日付のデータが取得できない
• 原因：日付条件の比較方法が誤っていた
• 対応：検索条件を修正した

このように整理することで、

• 同じ原因のバグを防げる
• 類似箇所の確認ができる
• 後から見ても理解できる

ようになります。

また、障害管理表は「記録」としても重要です。

後から振り返ったときに、

• どんなバグが多かったか
• どこでミスが起きやすいか

といった傾向も見えてきます。

つまり、障害管理表は単なるメモではなく、

バグを確実に潰し、再発を防ぐための仕組み

です。

3. データマートの要件とのすり合わせ（結合テスト）

これも最初は「なんでこんな確認するの？」と思っていました。

単体テストで動いているなら、それで十分に見えてしまうからです。

でも実際は、ここでズレがかなりの確率で見つかります。

例えば、

• データの結合条件が違う
• 想定しているデータ範囲が違う
• NULLの扱いが違う
• 集計ロジックが要件とズレている

といった問題です。

単体テストでは「その処理単体が正しいか」しか見ていません。

一方で、結合テストでは、

• 他のテーブル
• 他のシステム
• 実際のデータ

と組み合わせたときにどうなるかを確認します。

ここで初めて、

「仕様として正しいか」

が見えてきます。

特にデータマートのような集計系では、

• 元データの粒度
• 結合キー
• 集計単位

が少しでもズレると、結果が大きく変わります。

そしてこのズレは、コードだけ見ていても気づきにくいです。

実際にデータを流してみて初めて分かります。

結合テストは、

実際の利用に近い状態で動かして、仕様とのズレを確認する工程 です。

つまり、

「動くかどうか」ではなく「正しいかどうか」を確認するための作業 です。

まとめ

• SQLのステップ数
• 障害管理表
• 結合テストでの要件とのすり合わせ

あたりが特に「なんでやるの？」状態でした。

でも整理すると、それぞれの役割はシンプルです。

項目	目的
SQLのステップ数	作業量を把握する
障害管理表	バグを確実に管理する
結合テスト・すり合わせ	仕様どおり動くか確認する

全部に共通しているのは、

認識ズレと漏れを防ぐため

という点です。

• ステップ数 → 作業量の認識ズレを防ぐ
• 障害管理表 → 対応漏れや再発を防ぐ
• 結合テスト → 仕様とのズレを防ぐ

最初は意味が分からなくても大丈夫ですが、
「何を防ぐための作業なのか」を意識すると理解しやすくなります。

ただ言われたことをやるだけでなく、
「これは何のためにあるのか」「なんで工数を取って作業する必要があるのか」を考えるようになると、
仕事の見え方が少し変わってくると感じました。