💻 コーディング基礎講座【第六回・最終回】テスト・ファイル構造・バージョン管理を学ぼう！

1. 👋 はじめに

前回はエラーハンドリング（例外処理・防御的プログラミング）を学びました。

最終回は テスト・ファイル構造・バージョン管理 の3つを解説します！

「動くコードを書く」だけがエンジニアの仕事ではありません。
「長く・チームで・安心して使えるコード」を作るために、
テスト・整理・記録の3つが欠かせません。

---

2. 🧪 ユニットテストの基本

テストとは？

テストとは「コードが期待通りに動くことを自動で確認する仕組み」です。
手動で動作確認するのではなく、コードでコードをテストします。

なぜテストが必要なのか

手動確認（テストなし）	自動テスト（テストあり）
毎回手動で確認が必要	コマンド一発で全部確認できる
修正したら全部再確認が必要	影響範囲を自動で検出できる
確認漏れが起きやすい	漏れなく確認できる
チームに入った人が怖くて触れない	安心してコードを変更できる

💡 「テストは保険」
テストがあると「修正してもちゃんと動くか」を即座に確認できます。
テストがないコードは「何かを変えると何かが壊れるかもしれない」という恐怖との戦いになります。

ユニットテストの書き方（Python・pytest）

# calc.py（テスト対象のコード）
def add(a: int, b: int) -> int:
    """2つの数値を足し算する。

    Args:
        a: 1つ目の数値
        b: 2つ目の数値

    Returns:
        合計値
    """
    return a + b

def divide(a: int, b: int) -> float:
    """2つの数値を割り算する。

    Args:
        a: 割られる数
        b: 割る数

    Returns:
        商

    Raises:
        ValueError: bが0の場合
    """
    if b == 0:
        raise ValueError("ゼロで割ることはできません")
    return a / b

# test_calc.py（テストコード）
import pytest
from calc import add, divide

class TestAdd:
    """add関数のテスト。"""

    def test_正の数同士を足す(self) -> None:
        """正の数同士の足し算が正しいことを確認する。"""
        assert add(3, 5) == 8

    def test_負の数を足す(self) -> None:
        """負の数を含む足し算が正しいことを確認する。"""
        assert add(-3, 5) == 2

    def test_ゼロを足す(self) -> None:
        """ゼロを足した場合に値が変わらないことを確認する。"""
        assert add(5, 0) == 5


class TestDivide:
    """divide関数のテスト。"""

    def test_正常な割り算(self) -> None:
        """通常の割り算が正しいことを確認する。"""
        assert divide(10, 2) == 5.0

    def test_ゼロで割るときに例外が発生する(self) -> None:
        """ゼロで割った場合にValueErrorが発生することを確認する。"""
        with pytest.raises(ValueError) as exc_info:
            divide(10, 0)
        assert "ゼロで割ることはできません" in str(exc_info.value)

# テストの実行
pytest test_calc.py -v

# 出力例
# test_calc.py::TestAdd::test_正の数同士を足す PASSED
# test_calc.py::TestAdd::test_負の数を足す PASSED
# test_calc.py::TestAdd::test_ゼロを足す PASSED
# test_calc.py::TestDivide::test_正常な割り算 PASSED
# test_calc.py::TestDivide::test_ゼロで割るときに例外が発生する PASSED
# 5 passed in 0.12s ✅

ユニットテストの書き方（TypeScript・Vitest）

// calc.ts（テスト対象のコード）
export function add(a: number, b: number): number {
  return a + b;
}

export function divide(a: number, b: number): number {
  if (b === 0) {
    throw new Error("ゼロで割ることはできません");
  }
  return a / b;
}

// calc.test.ts（テストコード）
import { describe, it, expect } from "vitest";
import { add, divide } from "./calc";

describe("add", () => {
  it("正の数同士を足す", () => {
    expect(add(3, 5)).toBe(8);
  });

  it("負の数を含む足し算", () => {
    expect(add(-3, 5)).toBe(2);
  });
});

describe("divide", () => {
  it("通常の割り算", () => {
    expect(divide(10, 2)).toBe(5);
  });

  it("ゼロで割ったら例外が発生する", () => {
    expect(() => divide(10, 0)).toThrow("ゼロで割ることはできません");
  });
});

良いテストの3原則

原則	内容
🎯 1テスト1確認	1つのテストは1つのことだけ確認する
📖 テスト名で意図がわかる	「何をテストするか」がテスト名でわかる
🔁 何度実行しても同じ結果	外部に依存せず・実行順序に関係なく同じ結果になる

テストしやすいコードを書く

# ❌ テストしにくいコード（外部に依存している）
def get_discount_price(product_id: int) -> int:
    """割引価格を返す。"""
    product = db.find(product_id)  # DBに直接アクセス
    now = datetime.now()           # 現在時刻に依存
    if now.hour < 12:
        return int(product.price * 0.9)
    return product.price

# ✅ テストしやすいコード（依存を外から渡す）
def get_discount_price(price: int, current_hour: int) -> int:
    """割引価格を返す。

    Args:
        price: 元の価格
        current_hour: 現在の時間（0〜23）

    Returns:
        割引後の価格（午前中は10%引き）
    """
    if current_hour < 12:
        return int(price * 0.9)
    return price

# テストが簡単に書ける！
assert get_discount_price(1000, 10) == 900   # 午前中は10%引き
assert get_discount_price(1000, 15) == 1000  # 午後は割引なし

💡 「外から渡す」だけでなぜテストしやすくなるのか？

修正前は関数の中で datetime.now() を呼んでいたため、「午前中の割引をテストしたければ、本当に午前中にコマンドを実行しなければならない」という状況でした。

修正後は current_hour を引数として受け取るようにしたため、
10（午前10時）や 15（午後3時）を自由に渡せます。
「時間を外からコントロール」して渡せるようになったので、いつでも好きな時間のテストが自動化できます。

このように「外部に依存するもの（時刻・DB・APIなど）を引数として受け取る」設計を
依存性の注入（Dependency Injection） と呼びます。
テストしやすいコードは、設計としても柔軟で良いコードになっています。

---

3. 📁 ファイル・ディレクトリ構造

なぜ構造を整えるのか

「コードは書く場所も設計のうち」
ファイルの置き場所が整っていると、新しいメンバーがプロジェクトに入ってきたとき「どこに何があるか」がすぐわかります。

Python プロジェクトの基本構造

my_project/
├── src/                    # アプリケーションのソースコード
│   ├── __init__.py
│   ├── main.py             # エントリーポイント
│   ├── models/             # データモデル
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── order.py
│   ├── services/           # ビジネスロジック
│   │   ├── __init__.py
│   │   ├── user_service.py
│   │   └── order_service.py
│   └── utils/              # 汎用ユーティリティ
│       ├── __init__.py
│       └── email_helper.py
├── tests/                  # テストコード
│   ├── test_user_service.py
│   └── test_order_service.py
├── .env                    # 環境変数（Gitに含めない！）
├── .gitignore              # Gitで管理しないファイルの設定
├── requirements.txt        # 依存パッケージのリスト
└── README.md               # プロジェクトの説明

TypeScript（Next.js）プロジェクトの基本構造

my-app/
├── src/
│   ├── app/                # ページ・ルーティング（App Router）
│   │   ├── page.tsx        # トップページ
│   │   └── users/
│   │       └── page.tsx    # ユーザー一覧ページ
│   ├── components/         # 再利用可能なUIコンポーネント
│   │   ├── Button.tsx
│   │   └── UserCard.tsx
│   ├── lib/                # ユーティリティ・ヘルパー関数
│   │   └── api.ts
│   └── types/              # 型定義
│       └── user.ts
├── tests/                  # テストコード
│   └── components/
│       └── Button.test.tsx
├── .env.local              # 環境変数（Gitに含めない！）
├── .gitignore
├── package.json            # 依存パッケージのリスト
└── README.md

ファイル分割の目安

状況	判断
1ファイルが200行を超えてきた	分割を検討するタイミング
「このファイルは何をするファイルか」が説明しにくい	責任が混在している可能性あり
同じコードを別のファイルからも使いたい	共通モジュールに切り出す
テストが書きにくい	依存関係が複雑になっている可能性あり

---

4. 📝 バージョン管理（Git）

コミットメッセージの書き方

コミットメッセージは「未来の自分や仲間への手紙」です。
git log を見たとき「なぜこの変更をしたか」がわかるように書きましょう。

悪いコミットメッセージ vs 良いコミットメッセージ

❌ 悪い例	問題点
fix	何を直したかわからない
修正	何を修正したかわからない
wip	作業中という意味だが何の作業かわからない
aaa	論外
いろいろ直した	「いろいろ」が何かわからない

💡 wip の正しい使い方
wip 単体のコミットをメインブランチに残すのはNGですが、「PCが壊れる前にリモートに退避したい」という場面では、自分の作業ブランチで一時的に使うことはあります。

その場合でも 具体的な内容を書く のがマナーです。

✅ wip: ユーザー登録フォームのバリデーション実装中
❌ wip

最終的にはそのコミットを1つに綺麗にまとめてから（git squash）
チームのブランチに合流させましょう。

✅ 良い例	良い理由
fix: ログイン時のパスワード検証バグを修正	何を・どう直したかわかる
feat: ユーザープロフィール編集機能を追加	新機能の追加とわかる
refactor: calculate_tax関数を定数を使うように変更	リファクタリングとわかる
docs: READMEにセットアップ手順を追加	ドキュメントの変更とわかる

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

多くのプロジェクトで採用されている Conventional Commits という規約があります。

<type>: <概要>

[本文（任意）]

[フッター（任意）]

タイプ	意味	例
feat	新機能の追加	feat: ユーザー登録機能を追加
fix	バグ修正	fix: メール送信が失敗する問題を修正
refactor	機能変更なしのコード改善	refactor: 重複した処理を関数に切り出す
docs	ドキュメントの変更	docs: APIドキュメントを更新
test	テストの追加・修正	test: ユーザーサービスのテストを追加
chore	ビルド・設定の変更	chore: 依存パッケージをアップデート
style	コードスタイルの変更	style: インデントをスペース4つに統一

小さな単位でコミットする

# ❌ 1つのコミットに大量の変更を詰め込む
git commit -m "ユーザー機能の実装、バグ修正、テスト追加、ドキュメント更新"

# ✅ 1つのコミットは1つの変更
git commit -m "feat: ユーザー登録APIのエンドポイントを追加"
git commit -m "test: ユーザー登録APIのテストを追加"
git commit -m "docs: ユーザー登録APIのドキュメントを追加"

小さくコミットするメリット：

メリット	説明
🔍 レビューしやすい	変更点が小さいと何をしたかわかりやすい
↩️ 戻しやすい	問題のあるコミットだけ取り消せる
🐛 バグの原因を特定しやすい	git bisect で問題のコミットを絞り込める

.gitignoreで管理しないファイルを指定する

# .gitignore の例

# 環境変数（APIキー・パスワードが含まれる）
.env
.env.local
.env.production

# 依存パッケージ（npm installで再生成できる）
node_modules/

# Pythonのキャッシュ
__pycache__/
*.pyc

# IDEの設定ファイル（個人の設定は共有しない）
.vscode/settings.json
.idea/

# ビルド成果物
dist/
build/

⚠️ .env ファイルは絶対にGitにコミットしない！
APIキーやパスワードが含まれるため、
一度でもコミットすると履歴に残り続けます。
.gitignore への追加を最初に必ず行いましょう。

💡 代わりに .env.example をGitで管理する！

「.env をコミットしないなら、他のチームメンバーはどの環境変数が必要かどうやって知ればいいの？」という問題があります。

解決策は 値だけを空にした .env.example をGitに含める ことです。

# .env.example（Gitに含める・値は空にする）
DATABASE_URL=
API_KEY=
JWT_SECRET=

# .env（Gitに含めない・実際の値を書く）
DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=sk-1234567890abcdef
JWT_SECRET=my-super-secret-key

運用の流れ：
① .env.example をGitで共有
② 新しいメンバーが参加したら .env.example をコピーして .env を作る
（※ .env.txt のように拡張子をつけないよう注意！環境変数が読み込まれなくなります）
③ 各自が自分の環境の値を入力して使う

これで「どんな環境変数が必要か」をチームで共有しつつ、
実際の値は安全に管理できます🔒

---

5. 🎯 シリーズ総まとめ

6回にわたって学んだ内容を振り返りましょう。

回	テーマ	重要ポイント
第一回	コードの基本構造	順次・分岐・反復・関数・スコープ・型
第二回	命名規則	キャメル・スネーク・パスカル・良い名前の基準
第三回	コードの設計原則	DRY・KISS・単一責任・SOLID原則
第四回	コメント・ドキュメント	「なぜ」を書く・docstring・マジックナンバー排除
第五回	エラーハンドリング	例外処理・ガード節（早期リターン）・防御的プログラミング
第六回	テスト・構造・バージョン管理	ユニットテスト・ファイル整理・コミット規約

「良いコード」の共通点：

✅ 読んで意味がわかる（命名・コメント）
✅ 変更しやすい（設計原則・単一責任）
✅ 壊れにくい（エラーハンドリング・テスト）
✅ 迷わず使える（ファイル構造・バージョン管理）

これらはすべて「未来の自分やチームへの思いやり」から来ています。
コーディングの基礎は「技術」である前に「文化」です💪

📍 次の一歩：今日からできること

全6回を読み終えたあなたへ。
難しく考えなくて大丈夫です。

• 今書いているコードの変数に、1つだけ具体的な名前をつけてみる
• 長くなってきた関数を、1つだけ20行以内に収めてみる
• コミットメッセージを、1つだけ feat: や fix: で始めてみる

その小さな一歩の積み重ねが、
あなたを素晴らしいエンジニアに育ててくれます🌟

このシリーズが、より良いコードを書くための第一歩になれば幸いです。

💬 質問や感想があれば、コメント欄でお気軽にどうぞ!
👍 役に立ったら、いいね&ストックをお願いします!
🎓 ここまで読んでくださって、本当にありがとうございました!

---

🔗 シリーズ記事

• 【第一回】コードの基本構造
• 【第二回】命名規則
• 【第三回】コードの設計原則
• 【第四回】コメント・ドキュメント
• 【第五回】エラーハンドリング
• 【第六回】テスト・ファイル構造・バージョン管理（この記事）