第7章

開発の基礎知識

さまざまな言語のコード規約、ツール設定、ベストプラクティスを習得し、プロフェッショナルな開発習慣を身につけ、コード品質とチーム協働の効率を向上させる。

Sequential Thinking を使って開発の基本を学ぶ

開発の常識は多くの側面に関わり、使用構造化思考の方法次の内容を体系的に習得するのに役立ちます：

コード規約

異なる言語における命名、フォーマット、コメントの規約

ツール設定

ESLint、Prettier、フォーマットツールの実際の設定

ベストプラクティス

エラー処理、ログ、パフォーマンス、セキュリティなどの実践

継続的改善

コードレビュー、品質指標、技術的負債の管理

コード規約

統一されたコード規約はコードを読みやすく、保守しやすくし、チーム協業の基盤となります。言語ごとに規約は異なるため、以下では言語別に紹介します。

命名規則

変数/関数

camelCase

getUserName, calculateTotal

クラス/コンポーネント

PascalCase

UserProfile, LoginForm

定数

UPPER_SNAKE_CASE

MAX_RETRY_COUNT, API_BASE_URL

ファイル

kebab-case

user-service.ts, login-form.tsx

ESLint 設定

推奨 Airbnb または TypeScript ESLint 設定。

.eslintrc.json（Airbnb + TypeScript）：

{
  "extends": [
    "airbnb-base",
    "airbnb-typescript/base",
    "plugin:@typescript-eslint/recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking"
  ],
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "project": "./tsconfig.json"
  },
  "rules": {
    "@typescript-eslint/no-explicit-any": "error",
    "@typescript-eslint/explicit-function-return-type": "warn",
    "import/prefer-default-export": "off",
    "max-len": ["error", { "code": 100 }]
  }
}

Prettier 設定

.prettierrc：

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "arrowParens": "always"
}

TypeScript の厳格モード

tsconfig.json（厳格モード）：

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true
  }
}

React 规范

• 関数コンポーネントと Hooks を使用し、クラスコンポーネントを避ける
• Props は TypeScript インターフェースで定義する
• コンポーネント名は PascalCase を使用
• 必要に応じて React.memo を使用してパフォーマンスを最適化
• カスタム Hooks は `use` で始める

他の言語のクイックリファレンス

Rust

• rustfmt（整形）
• clippy（コードチェック）
• snake_case 命名

• dotnet format
• EditorConfig
• PascalCase 命名

Swift/Kotlin/Dart

• Swift: SwiftLint
• Kotlin: ktlint
• Dart: dart format

バージョン管理

Git は現代開発の標準ツールです。Git のワークフロー、ブランチ戦略、コードレビューの流れを習得することは、チーム協業の基盤です。

ブランチ戦略

Git Flow

• main：本番環境

• develop：開発ブランチ

• feature/*：機能ブランチ

• release/*：リリースブランチ

• hotfix/*：ホットフィックス

GitHub Flow

• main：メインブランチ

• feature/*：機能ブランチ

• PR によってマージする

• 継続的デプロイに適している

GitLab Flow

• main：メインブランチ

• 環境ブランチ（staging、production）

• 上流優先の原則

コミットメッセージ規約（Conventional Commits）

形式：<type>(<scope>): <subject>

feat(auth): ユーザーログイン機能を追加

fix(api): データ検索のパフォーマンス問題を修正

docs(readme): インストール手順を更新

refactor(utils): 日付フォーマット関数をリファクタリング

feat

新機能

fix

バグを修正する

docs

ドキュメント更新

style

コード形式

refactor

リファクタリング

test

テスト

chore

ビルド/ツール

perf

パフォーマンス最適化

Git Hooks の設定

pre-commit Hook

# 提出前に lint とフォーマットチェックを実行する
npm run lint
npm run format:check

commit-msg Hook

# コミットメッセージの形式を確認する
npx commitlint --edit $1

💡 使用 husky（Node.js）または pre-commit（Python）Git Hooksを管理する

コードレビューのプロセス

1機能ブランチを作成し、開発を完了してコードをコミットする

2Pull Request を作成し、PR の説明とチェックリストを記入する

3コードレビュー担当者がコードをレビューする（機能、パフォーマンス、セキュリティ、保守性）

4フィードバックに基づいてコードを修正し、再送信する

5レビュー承認後にメインブランチへマージ

依存関係の管理

プロジェクトの依存関係を適切に管理し、保守性と安全性を確保する。言語ごとに依存関係の管理方法は異なります。

セマンティックバージョニング（SemVer）

メジャーバージョン（MAJOR）

互換性のない API 変更

2.0.0

マイナーバージョン番号（MINOR）

後方互換性のある機能追加

1.2.0

改訂番号（PATCH）

後方互換性の問題修正

1.2.3

バージョン範囲：^1.2.3（1.x.x を許可、2.0.0 は許可しない）、~1.2.3（1.2.x を許可、1.3.0 は許可しない）

ファイル管理のロック

Node.js

• package-lock.json（npm）
• yarn.lock（yarn）
• pnpm-lock.yaml（pnpm）
• バージョン管理にコミットして、一貫性を確保する

Python

• requirements.txt（pip）
• poetry.lock（Poetry）
• Pipfile.lock（Pipenv）
• 仮想環境を使用して依存関係を分離する

依存関係セキュリティ監査

Node.js

npm audit

npm audit fix

yarn audit

pnpm audit

Python

pip-audit

safety check

bandit（コードの安全性チェック）

💡 使用 Dependabot または Renovate 依存関係とセキュリティパッチを自動更新する

依存関係更新戦略

• 定期的に更新：毎月1回、古くなった依存関係を確認する
• 安全優先：セキュリティ脆弱性のある依存関係を優先的に更新する
• テスト駆動：更新後に完全なテストスイートを実行する
• 段階的更新：主要な依存関係を一度に1つずつ更新し、大規模な変更を避ける
• ドキュメント記録：重大な依存関係の更新と移行手順を記録する

エラー処理の規約

適切なエラーハンドリングにより、プログラムはより堅牢になり、ユーザー体験も向上します。言語ごとに異なるエラーハンドリングのパターンがあります。

エラー種類の分類

業務エラー

• ユーザー入力エラー
• ビジネスルール違反
• 親切なエラーメッセージを返す

システムエラー

• データベース接続に失敗しました
• ファイルシステムエラー
• 詳細なログを記録する

ネットワークエラー

• API 呼び出しの失敗
• タイムアウトエラー
• リトライ機構を実装する

エラー処理モード

TypeScript/JavaScript/Python/Java：

try {
  const result = await riskyOperation();
  return result;
} catch (error) {
  logger.error('操作失败', { error });
  throw new BusinessError('ユーザーフレンドリーなエラーメッセージ');
}

エラー処理のベストプラクティス

• エラーの種類を明確にする：明確なエラー種別とエラーコードを定義する
• エラーログを記録する：完全なエラー情報とコンテキストを記録する
• ユーザーフレンドリーなヒント：ユーザーに親しみやすいエラーメッセージを表示し、技術的な詳細を隠す
• エラー回復：再試行、フォールバックなどの復旧メカニズムを提供
• エラー境界：エラー境界（React）またはミドルウェア（Express）を使用してエラーを一元的に処理する

ログ規約

優れたログ記録はデバッグと監視の基盤です。構造化ログにより、ログの分析と処理が容易になります。

ログレベル

DEBUG

詳細なデバッグ情報

開発デバッグ

INFO

一般情報

通常操作

WARN

警告メッセージ

潜在的な問題

ERROR

エラーメッセージ

エラーだが回復可能

FATAL

致命的なエラー

システムはこれ以上続行できません

構造化ログ（JSON形式）

例：

{
  "timestamp": "2025-01-27T10:30:00Z",
  "level": "ERROR",
  "message": "ユーザーログインに失敗しました",
  "context": {
    "userId": "12345",
    "ip": "192.168.1.1",
    "userAgent": "Mozilla/5.0..."
  },
  "error": {
    "type": "AuthenticationError",
    "message": "パスワードが間違っています",
    "stack": "..."
  },
  "requestId": "req-abc123"
}

ログコンテキスト

必須フィールド

• timestamp：タイムスタンプ
• level：ログレベル
• message：ログメッセージ
• requestId：リクエスト ID（追跡）

オプション項目

• userId：ユーザー ID
• operation：操作タイプ
• duration：操作にかかった時間
• metadata：追加のメタデータ

機密情報のマスキング

• パスワード：パスワードを絶対に記録しない、使用する *** 代替
• Token：Token の先頭数文字と末尾数文字のみ記録する
• 身分証番号：匿名化処理、数字の一部のみ表示
• 銀行カード番号：末尾 4 桁のみ表示
• メールアドレス：一部のマスキングを検討できます（例：u***@example.com）

パフォーマンス最適化

パフォーマンス最適化は継続的なプロセスです。コードレベルからアーキテクチャレベルまで、最適化の余地があります。

コードのパフォーマンス最適化

アルゴリズム最適化

• 適切なデータ構造を選択する（HashMap vs List）
• ネストしたループを避け、インデックスまたは Map を使用する
• キャッシュを使用して重複計算を回避する
• 時間計算量の分析（O(n) 対 O(n²)）

フロントエンドの最適化

• コード分割と遅延読み込み
• 画像最適化（WebP、遅延読み込み）
• React.memo を使用して不要な再レンダリングを回避する
• 仮想スクロール（長いリスト）

データベースクエリ最適化

インデックス最適化

• よく使われる検索フィールドにインデックスを追加する
• 過度なインデックス作成を避ける（書き込み性能に影響）
• 複合インデックスを使用して複数フィールドのクエリを最適化する
• 定期的にクエリ計画（EXPLAIN）を分析する

クエリ最適化

• SELECT * を避け、必要なフィールドのみを問い合わせる
• ページネーションを使用して、一度に大量のデータを読み込まない
• 複数回のクエリの代わりに JOIN を使用する
• N+1 クエリ問題を回避する

キャッシュ戦略

メモリキャッシュ

• ローカルキャッシュ（Map、LRU Cache）
• ホットデータに適している
• メモリ制限に注意

Redis

• 分散キャッシュ
• 有効期限を設定
• キャッシュの貫通/撃ち抜き/雪崩対策

CDN

• 静的アセットの高速化
• 画像、CSS、JS ファイル
• エッジノードキャッシュ

パフォーマンス監視

• APM ツール：New Relic、Datadog、Sentry（パフォーマンス監視）
• パフォーマンス分析：Chrome DevTools、Python cProfile、Go pprof
• 指標監視：応答時間、スループット、エラー率、リソース使用率
• アラート機構：パフォーマンスのしきい値を設定し、しきい値を超えたら自動で警告

セキュリティのベストプラクティス

セキュリティは任意ではなく、必須です。コードレベルからデプロイレベルまで、すべての段階でセキュリティを考慮する必要があります。

入力の検証とクリーンアップ

フロントエンド検証

• Zod、Yup などのライブラリを使用してフォーム入力を検証する
• クライアント側の検証でユーザー体験が向上する
• ただし、フロントエンドの検証のみに依存してはいけない

バックエンド検証

• すべての入力は検証しなければならない
• ブラックリストではなくホワイトリストを使用する
• ユーザー入力をクリーンアップしてエスケープする

一般的な攻撃への防御

SQLインジェクション

• パラメータ化クエリ（Prepared Statements）を使用する
• ORM（Prisma、TypeORM）を使用
• SQL 文字列を決して連結しない

XSS（クロスサイトスクリプティング）

• 出力のエスケープ（Reactの自動エスケープ）
• Content Security Policy（CSP）を使用する
• dangerouslySetInnerHTML の使用を避ける

CSRF（クロスサイトリクエストフォージェリ）

• CSRF Token を使用する
• SameSite Cookie 属性
• Referer ヘッダーを検証する

機密データの暗号化

• パスワードは bcrypt、Argon2 でハッシュ化する
• 通信は HTTPS（TLS）を使用する
• 機密データを保存する際は暗号化する

秘密鍵管理

環境変数

• .env ファイルを使用する（Git にコミットしない）
• .env.example をテンプレートとして使用する
• 本番環境ではキー管理サービスを使用する

鍵管理サービス

• AWS Secrets Manager
• HashiCorp Vault
• Azure Key Vault
• 定期的にキーをローテーションする

OWASP Top 10 防御

1.注入攻撃（SQL、NoSQL、コマンドインジェクション）

2.認証の失敗

3.機密データの漏洩

4.XML 外部実体（XXE）

5.無効なアクセス制御

6.安全な設定ミス

7.XSS クロスサイトスクリプティング

8.安全でないデシリアライズ

9.既知の脆弱性を含むコンポーネントを使用する

10.不十分なログ記録と監視

コードレビュー

コードレビューはコード品質を保証するための重要な工程です。明確なレビュー手順とチェックリストを整備し、レビューをより効率的にしましょう。

レビューチェックリスト

機能

☐ 機能は要件を満たしているか
☐ 境界ケースは処理されているか
☐ エラー処理は十分か
☐ テストは十分か

性能

☐ パフォーマンスの問題はありますか
☐ データベースクエリは最適化されているか
☐ メモリリークはあるか
☐ キャッシュの使用は適切か

安全

☐ 入力検証が完全かどうか
☐ 機密情報が漏洩していないか
☐ 権限チェックは正しいか
☐ 依存関係にセキュリティ脆弱性がないか

保守性

☐ コードは明確で読みやすいか
☐ 命名規則は適切か
☐ コメントは十分か
☐ プロジェクト規約に従っているか

レビューのベストプラクティス

タイムリーなレビュー：PR 作成後、できるだけ早くレビューし、開発の停滞を避ける

建設的なフィードバック：問題を指摘し、改善提案を行うのであって、ただ批判するだけではない

小規模バッチレビュー：レビューごとのコード量を400行以内に抑える

自動化チェック：CI/CD を使用してフォーマット、テスト、セキュリティを自動チェック

継続的改善

コード品質は一度きりの作業ではなく、継続的に改善するプロセスです。品質指標と監視メカニズムを構築しましょう。

コード品質指標

循環複雑度

• コードの複雑さを測定する
• 目標：< 10
• ツール：SonarQube、CodeClimate

コードカバレッジ

• テストでカバーされているコードの割合
• 目標：> 80%
• ツール：Jest、Coverage.py、JaCoCo

技術的負債

• コードの悪臭、重複コード
• 定期的にリファクタリングする
• ツール：SonarQube

自動化チェック（CI/CD 統合）

GitHub Actions の例：

name: Code Quality

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
      - name: Install dependencies
        run: npm ci
      - name: Run linter
        run: npm run lint
      - name: Run tests
        run: npm test
      - name: Check coverage
        run: npm run test:coverage

技術的負債管理

• 負債を特定する：ツールを使ってコードの臭いと重複コードを自動的に検出する
• 優先順位付け：影響範囲と修正コストに基づいて優先順位を付ける
• 定期的なリファクタリング：各 Sprint に一定時間を割り当ててリファクタリングする
• 負債を記録する：Issue または技術的負債リストに記録する
• 新たな技術的負債を避ける：コードレビュー時に技術的負債に注意する

学習成果

この章を終えると、あなたは：

1さまざまな言語のコード規約（TypeScript、Python、Java、Go など）とツール設定を習得する
2Git を使ったバージョン管理に習熟し、ブランチ戦略とコードレビューのプロセスを習得する
3依存関係管理の重要性を理解し、セキュリティ監査と更新戦略を習得する
4エラー処理とログ規約を身につけ、コードの堅牢性を高める
5パフォーマンス最適化とセキュリティのベストプラクティスを理解し、高品質なコードを記述する
6コードレビューと継続的改善の仕組みを構築し、チームのコード品質を向上させる

前の章：AI アプリケーションフレームワーク全景次章：インターフェースの相互作用

開発の基礎知識

コード規約

命名規則

ESLint 設定

Prettier 設定

TypeScript の厳格モード

React 规范

他の言語のクイックリファレンス

バージョン管理

ブランチ戦略

コミットメッセージ規約（Conventional Commits）

Git Hooks の設定

コードレビューのプロセス

依存関係の管理

セマンティックバージョニング（SemVer）

ファイル管理のロック

依存関係セキュリティ監査

依存関係更新戦略

エラー処理の規約

エラー種類の分類

エラー処理モード

エラー処理のベストプラクティス

ログ規約

ログレベル

構造化ログ（JSON形式）

ログコンテキスト

機密情報のマスキング

パフォーマンス最適化

コードのパフォーマンス最適化

データベースクエリ最適化

キャッシュ戦略

パフォーマンス監視

セキュリティのベストプラクティス

入力の検証とクリーンアップ

一般的な攻撃への防御

秘密鍵管理

OWASP Top 10 防御

コードレビュー

レビュー チェックリスト

レビューのベストプラクティス

継続的改善

コード品質指標

自動化チェック（CI/CD 統合）

技術的負債管理

学習成果

レビューチェックリスト