おい、この問題は本当に古典的で、エンジニアなら誰もが一度は悩む「究極の問い」だ。オフィスでドキュメントのことで揉めるのは、コードスタイルで揉めるのと同じくらい、いやそれ以上に多い。
正直なところ、「XXページ書け」とか「XX文字書け」といった標準的な答えはない。もし誰かが「すべての関数にコメントを書け」なんて言ってきたら、そいつはブロックしてしまっていい。特にスタートアップ企業でそんなことをしていたら、プロジェクトはとっくに頓挫しているだろう。
重要なのは「量」ではなく、「誰のために書くのか」と「どのような状況で読まれるのか」だ。ドキュメントは、未来の誰かに話しかけていると想像してみてほしい。その「誰か」とは、例えばこんな人たちだ。
- 3ヶ月後の自分: （「あの時、なんでこんなクソコード書いたんだっけ？」）
- 新しく入社した同僚: （「先輩、このプロジェクトどうやって動かすんですか？ローカルでデバッグしたいんですけど。」）
- 真夜中にバグ修正のために呼び出された、もう一人の不運な同僚: （「このAPIは何をするんだ？なんでこんな変なデータが返ってくるんだ？」）
- 自分が作ったモジュールを使う隣のチームの同僚: （「このツールどうやって使うんですか？何か例を教えてもらえませんか？」）
誰に話しかけているのかがはっきりすれば、何をどれくらい書けばいいのかがわかるはずだ。
いくつかシナリオ別の提案をするので、これを参考にすれば、チームの誰もドキュメントのことで文句を言ってくることはないだろう。
1. 「命綱」ドキュメント：必須。これがないと皆が破滅する
この種のドキュメントは最優先事項だ。量は多くないが、なければ大問題になる。
- プロジェクトの起動方法:
README.mdファイルに、以下の点を明確に記述する。- このプロジェクトは何をするものか（一文で説明）。
- 依存関係のインストール方法（
npm install、pip install -r requirements.txtなどのコマンド）。 - サービスの起動方法（
npm run dev、python manage.py runserver）。 - テストの実行方法。
- 目的: 新しい同僚が30分以内に自分のPCでプロジェクトを動かせるようにするため。一日中質問攻めにされるのを避けるための、新人への「救いの手」であり、自分自身の平穏のためでもある。
- 環境設定の説明: 例えば
.env.exampleファイルに、設定が必要な変数名をすべてリストアップし、その変数が何をするものなのかをコメントで説明する。パスワードや秘密鍵を直接書き込まないこと！- 目的: 環境設定の不備で午前中いっぱい悩むのを防ぐため。
- デプロイとリリースの手順: プロジェクトを手動でデプロイする必要がある場合、必ず手順を記録しておくこと。たとえチーム内だけが見られるメモアプリに記録するだけでも良い。
- 目的: デプロイできるのが自分一人だけという状況を防ぐため。もし自分が休暇を取ったら、プロジェクトをリリースできなくなってしまう。
2. 「道標」ドキュメント：コード内に記述し、コードを読む人を導く
この種のドキュメントは長文ではなく、コード内の「ハイライトされたコメント」だ。
- 「なぜ」そうするのか、ではなく「何が」そうするのか:
- 悪い例:
// ユーザーリストをループする(これは見ればわかるだろう？) - 良い例:
// ここでは通常のforEachを使わない。IE8の奇妙なバグに対応する必要があるため。 - 良い例:
// 警告：以下の関数のパフォーマンスは極めて悪い。一時的な解決策であり、将来的にはxxxパターンにリファクタリングする必要がある。
- 悪い例:
- 複雑なビジネスロジック: コードのビジネスロジックが非常に複雑な場合、例えばポイント計算やクーポン計算の関数などでは、関数の冒頭でルールを数行で明確に説明するのがベストだ。
- 例:
// 最終価格計算ルール：1. 割引率が最も高いクーポンを優先的に使用する。2. ポイントとクーポンは同時に使用できない。3. VIPユーザーはさらに5%割引。
- 例:
- APIインターフェースのコメント: バックエンドAPIを書いている場合、インターフェース定義の上に、そのAPIが何をするものか、必要なパラメータ、返される値を簡単に説明する。
- 目的: フロントエンドやクライアント側の同僚が、自分のコードを深く掘り下げなくても、APIの呼び出し方を知ることができるようにするため。最近の多くのフレームワークは、このようなコメントに基づいてAPIドキュメント（Swaggerなど）を自動生成できるため、一度書けばずっと使える。
3. 「取扱説明書」ドキュメント：自分の作ったものを使う人向け
もしあなたが共通コンポーネント、ツールライブラリ、または他の人が使うサービスを作った場合。
- すぐに使える例を提供する: 自分の設計哲学を長々と説明するのではなく、最もシンプルで、すぐに動くコードスニペットを直接提供し、他の人がコピー＆ペーストで使えるようにする。
- 主要なパラメータの説明: 最も重要なパラメータをいくつかリストアップし、それらが何をするものか、どのような選択肢があるかを説明する。
まとめ
ドキュメントを書くことを、余分で面倒なタスクだと考えないでほしい。それはコードの一部であり、未来とのコミュニケーションの一種だと捉えよう。
あなたの目標は『百科事典』のようなものを書くことではなく、以下の3点を達成することだ。
- 新人が自力で作業できるようにする。
- 協力者が自分で問題を調査できるようにする。
- 未来の自分が文句を言わないようにする。
この3点を達成できれば、あなたはチームで最も輝く存在となり、誰もドキュメントのことであなたを批判することはないだろう。最高のドキュメントとは、「ちょうど良い」ドキュメントだということを忘れないでほしい。重要な情報が欠けておらず、無駄な一言もないドキュメントこそがそれだ。