最近、テストベース開発（TDD）、関数ベース開発（BDD）、エクストリームプログラミング（XP）、スクラム、立ち会い、そして神は、ソフトウェアを作成しますが、作成するソフトウェアがユーザーの要件を満たさない場合、これらの手法はすべて意味がありません。 別に説明してみましょう。 不正な仕様の理想的な実装は役に立たない。 美しく書かれたライブラリの有用性は、ドキュメントがなければゼロになる傾向があります。 アプリケーションが問題を解決しない場合、または誰もそれを使用する方法を知らない場合、何か間違いなく間違っています。
わあ それでは、この問題をどのように解決しますか？ あなたが考えるよりも簡単で、別の段落で答えを強調するのに十分重要です。
まず、Readmeファイルを作成します。
そうです-最初のこと。 つまり、コードやテスト、機能、ユーザーストーリーなどの記述を開始する前であってもです。 私たちは開発者であり、テクニカルライターではありません。 しかし、ここであなたは間違っています。 Readmeを書くことは、優れたプログラムを書く上で不可欠な部分です。 書面でポイントを書くことができるまで、コードを書き始めることはできません。 滝型開発プロセスに対する大十字軍と柔軟な開発方法論の普遍的な受容の間で何かが失われました。 誤解しないでください：ウォーターフォール型の開発プロセスは遠すぎます。 最小の詳細まで記述された大規模なシステムは、最小の詳細まで記述された誤ったシステムでその存在を終わらせます。 反対すると決めたときは正しかった。 しかし、ウォーターフォール型の開発プロセスに取って代わったのは別の極端です。 現在、私たちは最小限の不十分なドキュメンテーションを伴うプロジェクトに直面しています。 一部のプロジェクトにはReadmeファイルさえありません！
これは受け入れられません。 技術仕様書の山とその不在の間には妥協点がなければなりません。 そして実際にそうです。 この中間点は、目立たない控えめなReadmeファイルです。
READMEベースの開発とドキュメントベースの開発（DDD）を区別することが重要です。 Readmeベースの開発方法論は、原則として、ドキュメントベースの開発のサブクラスまたは不完全なバージョンと見なすことができます。 設計ドキュメントを1つのファイルに限定することで、これは別の人にプログラムを紹介するファイルでもあるため、Readmeベースの開発方法論は、ドキュメンタリーベースの開発方法論が変容するウォーターフォール症候群からあなたを守り、長すぎると罰するライブラリを小さくモジュール化したままにしておくことで報酬を与えながら、仕様を詳細に飽和させます。 これらのシンプルなルールは、プロジェクトに沿って適切な方向に進みますが、あなたがすべてを正しく行っていることを制御することを目的とした不要なプロセスはありません。
はじめにReadmeファイルを作成することから始めて、次のような多くの重要な利点を作成します。
- 最も重要なことは、何か別のことをしたり、たとえばPublic APIで何が起こるかを選択するためにコードを変更することなく、プロジェクトについて考える機会を自分に与えることです。 コードの自動テストを最初に書き始めたときの感覚を覚えていますか？そうしないとコードベースに侵入する可能性のあるすべての種類のエラーをキャッチしたことに気付きましたか？ これは、コードの直接記述を開始する前にプロジェクトのReadmeファイルを記述した場合と同じ感覚です。
- また、実装するものを決定するためにReadmeファイルを作成する副産物として、すぐに素晴らしいドキュメントが手元にあります。 そして、プロジェクトを始めたばかりで、興奮とモチベーションが最大限にあるとき、このドキュメントを書くのがはるかに簡単で楽しいことがわかります。 Readmeをさかのぼって書くのは非常に退屈です。そうすると、重要な詳細を間違いなく見逃してしまいます。
- チームで作業している場合、Readmeファイルからさらに多くの利益を得ることができます。 コードの記述を完了する前にチームの全員がこの情報にアクセスできる場合、コードとやり取りするプロジェクトで自信を持って作業を開始できます。 そうでない場合、対話インターフェースが定義されていない場合、コードを順番に記述するか、コードの大部分を書き換える可能性があります。
- 記録された内容に基づいてディスカッションを行う方がはるかに簡単です。 何も説明されていない場合、サークルが同じことを繰り返した後、問題のサークルについて延々と議論することができます。 提案されたソリューションを記録するような単純なアクションは、誰もが後で挑戦し、繰り返すことができる特定のアイデアを持っていることを意味します。
プロジェクトのReadmeファイルを作成するプロセスを真の作成行為と考えてください。 これはまさにあなたのすべての素晴らしいアイデアが表現されるべき場所です。 あなたの創造性と自己表現の証拠として、この文書は別の場所を占めるべきです。 readmeファイルは、コードベースで最も重要なドキュメントである必要があります。 最初に作成するのは正しいことです。
注：- ソフトウェア開発技術者名の翻訳はここから取られます 。
- Corey OordtのPyCon 2011でのドキュメントによる開発原則に関する講演