PART 01 — 設計標準ドキュメント入門
はじめに・ドキュメントが必要な理由・コーディング規約

設計標準ドキュメントとは何か

設計標準ドキュメントとは、ソフトウェア開発においてチームが共通して従うべきルール・指針・判断基準をまとめた文書群です。コーディング規約、アーキテクチャ設計の方針、API設計のガイドライン、UI/UXの基準など、開発のあらゆる側面において「なぜそうするのか」「どうすればよいか」を明文化したものです。

単なる規則集ではなく、チームの集合知を記録し、意思決定の背景を伝える役割を担います。エンジニアが「この書き方で合っているのか」「この設計方針はチームの方向性と合致しているか」を判断する際の拠り所になります。

なぜドキュメント化が重要か

「口頭で共有しているから大丈夫」という状態がどれほど脆いか、多くのチームが痛い経験を通じて学んでいます。ドキュメント化の必要性を理解するために、まず「ドキュメントがない状態で何が起きるか」を具体的に見てみましょう。

ドキュメントがないと何が起きるか

このような問題は珍しくありません。「知識」が特定の人の頭の中にある限り、その人がチームを離れた瞬間に失われます。ドキュメント化は「知識を人から切り離し、チームの資産にする」プロセスです。

もう一つよくあるシナリオは「新メンバーのオンボーディングに毎回1ヶ月かかる」問題です。先輩エンジニアが毎回同じ説明を繰り返し、コードレビューで同じ指摘をし続ける。これは設計標準がドキュメント化されていれば大幅に改善できる非効率です。

ドキュメント化がもたらす4つの恩恵

特に「レビュー基準の統一」は、チームの心理的安全性にも直結します。ルールが明文化されていないと、レビューが「個人の好み」に見えてしまい、「あのレビュアーのときは厳しい」という不公平感が生まれます。標準があれば、レビューはルールの確認であり、個人攻撃ではないと全員が理解できます。

コーディング規約とは

コーディング規約は最も基本的な設計標準です。コードの見た目・構造・スタイルを統一することで、誰が書いても読みやすいコードベースを維持します。

コーディング規約が整備されていないと、コードレビューで「ここのインデントが違う」「この関数名はわかりにくい」という指摘が毎回繰り返されます。レビュアーの好みや気分によってフィードバックが変わるため、レビューが不公平に感じられたり、議論に時間をとられたりします。

コーディング規約の主なカバー範囲は以下の通りです。

実例：TypeScriptコーディング規約

TypeScriptプロジェクトでよくある規約違反と、その改善例を見ていきましょう。以下のコードは実際のレビューコメントをベースにしたものです。

// ❌ Bad: 略語・省略形の変数名
const u = await db.findUser(id);
const res = await api.get('/data');

// ✅ Good: 意図が明確な変数名
const user = await db.findUser(id);
const articleListResponse = await api.get('/articles');

// ❌ Bad: boolean変数にis/has/canプレフィックスなし
let loading = true;
let error = false;

// ✅ Good: boolean変数の命名
let isLoading = true;
let hasError = false;

// ❌ Bad: マジックナンバー（何を意味するか不明）
if (user.age >= 18) { /* ... */ }
setTimeout(fn, 86400000);

// ✅ Good: 定数として意味を持たせる
const ADULT_AGE = 18;
const ONE_DAY_MS = 24 * 60 * 60 * 1000;
if (user.age >= ADULT_AGE) { /* ... */ }
setTimeout(fn, ONE_DAY_MS);

命名規則に加えて、エラーハンドリングの規約も重要です。「エラーを握りつぶすな」という指摘はよくありますが、「どう書けばよいか」まで示すことでドキュメントの価値が高まります。

// ❌ Bad: エラーを握りつぶしている
async function fetchUser(id: number) {
  try {
    const user = await api.getUser(id);
    return user;
  } catch (e) {
    console.log(e);  // ログだけ出してundefinedを返す
  }
}

// ❌ Bad: エラー型が不明確（any型は使わない）
async function fetchUser(id: number) {
  try {
    return await api.getUser(id);
  } catch (e: any) {
    throw e;
  }
}

// ✅ Good: 型安全かつ呼び出し元で処理を委ねる
class UserNotFoundError extends Error {
  constructor(userId: number) {
    super(`User not found: ${userId}`);
    this.name = 'UserNotFoundError';
  }
}

async function fetchUser(id: number): Promise<User> {
  const user = await api.getUser(id);
  if (!user) {
    throw new UserNotFoundError(id);
  }
  return user;
}

Linter / Formatter との連携

コーディング規約はドキュメントとして書くだけでなく、ESLint・Prettier・RuboCop・gofmt などのLinter/Formatterと連携させることで、自動的に強制できます。「書いてあるが守られない」状態を防ぐために、ツールによる自動チェックをCIに組み込むことが理想です。

たとえばESLintの設定で「any 型の使用を禁止する」ルールを設けると、CIがPRをブロックするため、ドキュメントを読んでいなくても自然と準拠したコードが書かれるようになります。これが「ドキュメントの自動執行」の考え方です。

{
  "rules": {
    "@typescript-eslint/no-explicit-any": "error",
    "@typescript-eslint/no-unused-vars": "error",
    "prefer-const": "error",
    "no-console": ["warn", { "allow": ["error", "warn"] }],
    "eqeqeq": ["error", "always"],
    "no-var": "error"
  }
}

Prettierはフォーマットの自動修正に使います。「タブかスペースか」「セミコロンありかなしか」といった議論をPrettierに委ねることで、チームの議論コストをゼロにできます。

「ドキュメントで書いたルールは、可能な限りツールに落とし込む」という原則を守ると、人間が守るべきルールは「判断を要するもの（設計の意図・例外の判断など）」だけに絞られ、レビューの質が向上します。

既存ガイドをベースにする戦略

コーディング規約をゼロから作ると「タブかスペースか」のような不毛な議論が発散しやすいため、まず業界標準を採用し、例外事項のみを明記する方針を取ると良いでしょう。

「既存のガイドを参照しつつ、チーム固有のルールを追加する」形を取ることで、外部の知見を活かしながらチームの実情に合わせた規約を短時間で整備できます。