【Python】コードを書く前にレビューを受ける？「TODO駆動開発」で設計の手戻りをなくす方法

2025年10月17日

大規模な機能開発では、コードを書き進めてから設計上の問題に気づき、大幅な手戻りが発生することがあります。「このクラス設計、もっと良い方法があったな…」「この関数の責務が曖昧だった…」といった後悔は、多くの開発者が経験する痛みです。

もし、本格的なロジックを一行も書く前に、設計レビューを完了させられるとしたらどうでしょうか？

今回は、TODOコメントを設計図として活用し、実装の骨格（スケルトン）の段階でレビューを受ける**「TODO駆動開発」**とも呼べるプラクティスを紹介します。これは、チーム開発におけるフィードバックサイクルを劇的に高速化し、手戻りのリスクを最小限に抑えるための強力なテクニックです。

問題点：実装後に発覚する、コストの高い設計ミス

どんなに経験を積んだ開発者でも、自分一人で考えた設計の穴に事前に気づくのは難しいものです。

複雑な機能を一人で黙々と実装し、数日後に完成した数百行のプルリクエスト（PR）をレビューに出した結果、アーキテクチャの根本に関わる指摘を受けて大幅な修正が必要になる、といった事態は避けたいものです。コードを書くのに費やした時間が無駄になるだけでなく、精神的な負担も大きくなります。

解決策：「TODOコメント」を設計図としてレビューする

この問題を解決するのが、「スケルトンPR」や「疑似コードPR」とも呼ばれるアプローチです。具体的なロジックを実装する前に、関数の骨格と、その中で何を行うかの実装計画をTODOコメントとして記述し、その時点でレビューを依頼します。

例：「ユーザーが指定した条件でレポートを生成し、CSVでメール送信する」機能

この機能を実装する場合、いきなりCSV生成やメール送信のロジックを書き始めるのではなく、まず次のような「設計図」としてのコードを書きます。

reports/services.py （スケルトン実装）

from users.models import User
from reports.models import Report

class ReportGenerationError(Exception):
    """レポート生成時のカスタム例外"""
    pass

def _generate_csv_content(report: Report) -> str:
    """レポートデータからCSV形式の文字列を生成する。"""
    # TODO: 1. reportオブジェクトから関連データを取得する。
    # TODO: 2. `io.StringIO`と`csv.writer`を使って、メモリ上でCSVを組み立てる。
    # TODO: 3. ヘッダー行とデータ行を書き込む。
    # NOTE: データ量が多い場合、メモリは大丈夫か？ ストリーミングを検討すべき？
    #       (レビュー担当者への質問)
    pass

def _send_report_by_email(user: User, csv_content: str, report_name: str):
    """生成されたCSVをユーザーにメールで送信する。"""
    # TODO: 1. DjangoのEmailMessageクラスを利用する。
    # TODO: 2. CSVデータを添付ファイルとして設定する。
    # TODO: 3. ユーザーのメールアドレス宛に送信する。
    # 参考: https://docs.djangoproject.com/ja/4.2/topics/email/#email-attachments
    pass

def generate_and_email_report(user_id: int, report_id: int):
    """レポート生成とメール送信のメインロジック。"""
    # TODO: 1. user_idとreport_idで、それぞれのオブジェクトを取得する。
    # TODO: 2. _generate_csv_content() を呼び出す。
    # TODO: 3. _send_report_by_email() を呼び出す。
    # TODO: 4. 上記のプロセスでエラーが発生した場合の例外処理を実装する。
    #          - `ReportGenerationError`を定義して、それを捕捉する？
    #          - 失敗したことをユーザーに通知する必要はあるか？
    pass

このスケルトンコードを、**「ドラフトプルリクエスト（Draft PR）」**として作成し、チームにレビューを依頼します。その際のPRの説明文が非常に重要です。

PRタイトル: [WIP] レポートメール送信機能の設計レビュー依頼

説明: レポートメール送信機能の実装に着手する前に、全体の設計方針についてレビューをお願いします。

services.pyに上記3つの関数を配置する構成を考えています。TODOコメントに具体的な実装計画と、エラーハンドリングに関するいくつかの疑問点を記載しました。

このアーキテクチャで問題ないか、特にNOTEに書いた懸念点についてご意見をいただけると幸いです。

「TODO駆動開発」がもたらすメリット

最速のフィードバックループ: 実装に時間を費やす前に、設計に関するフィードバックを数時間、時には数分で得ることができます。
協調的な設計プロセス: TODOコメントに書かれた疑問点や懸念点が、チームでの設計議論のたたき台となり、より良い設計を生み出します。
無駄な実装の削減: レビューで指摘された設計変更は、本格的な実装前に反映されるため、書き直しのコストがほぼゼロになります。
明確な実装計画: 設計が承認されれば、あとはTODOコメントを一つずつ実際のコードに置き換えていくだけです。実装の道筋が明確になり、作業に集中できます。
未来のためのコンテキスト保持: ご指摘の通り、実装の根拠となったURLや議論の経緯をコメントとして残しておくことで、将来のコードメンテナンス時に「なぜこの実装になっているのか」が分かりやすくなります。