コードのドキュメントを最初に？[閉まっている]

実際にコードを記述する前に、完全なコードドキュメントを最初に作成しようとしたことがありますか？これについては、具体的なインターフェイスを記述し、クラスがどのように相互作用するかを考えさせることで、初期設計がフロア化されないようにするのに役立つと考えたため、以前考えていました。これはいいアイデアですか？誰もが試しましたか？エル

はい。

それは、あなたのコードが何をすべきかを正確に考えさせます。 アイデアは、コードの任意の部分から始めて、そのモジュールを完了するために何をする必要があるかを正確に知ることができるということです。

また、IDEよりも描画ボード上の何かを簡単に修正できます。

それについて考える方法は2つあります。

1）Word文書、Wikiなどの文書。定義により、文書化するコードがないため、完全なコード文書を作成することはできません。最初に、高レベルの設計、仮定、インターフェース、契約を文書化することができます。

2）実行可能テストとしてのドキュメント。実行可能な単体テストが最高のドキュメントであると述べる考え方があります。この考え方は、コード（TDD）を書く前に、この種のドキュメントを提唱しています。同時に、最初からシステム全体のすべてのテストを作成するわけではありません。最初にユースケースごとに分類し、次にユースケースごとにテストとコードを実行します。

ドキュメントから始まるのは古典的なウォーターフォールモデルであり、そのモデルに関連するすべての落とし穴があります。大まかに言うと、文書化するほど、要件が変わったときに更新する必要があります。ユーザーマニュアルから始めることの利点の1つは、フィードバック（および変更）がより早く得られることです。しかし、経験から、ほとんどの人はドキュメントをアクションに精神的にマッピングするのが苦手であることがわかります。そのため、代わりにプロトタイプを使用します。これにより、ユーザーは実際にソフトウェアを使用し、そのようにフィードバックを提供できます。

「最初の文書化」の1つのバリエーションは、リテラシープログラミングです。プログラマーの観点からプログラムが何をするかの説明を書くことから始めます。コンパイルするまで微調整してください。Voila、リテラシープログラム。

個人的には、ダイアグラム（UMLなど）を使用して単純なモデリングを行い、物の流れを示す方が良いと感じています。これは、物事を言葉で文書化するよりもはるかに迅速であり、正しく行われた場合も同様に記述的です。個人的に私が取り組んだプロジェクトはプログラミングの過程で変わっていなかったので、完全なドキュメントを作成することをためらいます。

編集：しかし、あなたが長く行くにつれていくつかのドキュメントを行う必要があります。これにより、後で完全なドキュメントを簡単に作成できます。

ジョシュア・ブロックは、本「Coders at Work」のインタビューでこの点について議論しています。

より正統的で学問的な見方とは反対に、彼はあなたの考えの調子に何かをアドバイスします（あなたはそれを自分で読んだかもしれませんか？） 「感じ。この目的のために、彼はインターフェースの一部とそれを使用するクライアントコードを設計しました。

最も重要なことは、あなたが構築しようとしているもの、つまりあなたが解決しようとしている問題を知ることです。要件分析の重要性を誇張することはできません。「ああ、そうだ、要件分析。顧客に行き、「何が必要ですか？」と言います。彼はあなたに言った、そしてあなたは終わった。」

真実と違うことがあってはならない。交渉だけでなく、理解のプロセスでもあります。多くの顧客はあなたに問題を伝えません。彼らはあなたに解決策を教えてくれます。たとえば、顧客は「次の17の属性のサポートをこのシステムに追加する必要があります。それから、「なぜ？システムで何をするつもりですか？どのように進化すると期待していますか？」など。すべての顧客がソフトウェアを実際に必要としていることを理解するまで、あなたは行き​​来します。これらはユースケースです。

この段階で実行できる最も重要なことは、適切なユースケースセットを考え出すことです。それができたら、可能な解決策を測定できるベンチマークがあります。間違った場合はすでに死んでいるので、かなりの時間をかけて適切に近づけるのに大丈夫です。残りのプロセスは無益さの練習になります。

あなたができる最悪のこと-そして私はこれが起こるのを見ました-あなたは6ヶ月間働くためにたくさんの賢い人を部屋に入れて、彼らがそれが何であるかを本当に理解する前に247ページのシステム仕様を書きます構築しようとしています。なぜなら、6か月後、彼らは非常に正確に指定されたシステムを持ち、それは役に立たないかもしれないからです。そして、彼らはしばしば「私たちはそれを構築しなければならないほど仕様に多大な投資をした」と言います。したがって、彼らは役に立たないシステムを構築し、それは決して使用されません。そしてそれは恐ろしいことです。ユースケースがない場合は、モノを構築し、非常に単純なことをしようとすると、「XMLドキュメントを取得して印刷するような非常に簡単なことを行うには、定型的なページのページが必要です」コード。" そしてそれは恐ろしいことです。

-ジョシュア・ブロッホ、ピーター・セイベルによる「職場のコーダー：プログラミングの技術に関する考察」のインタビューより

すでにこれらの方針に沿って考えている場合は、本を手に入れてインタビュー全体を読むことができればよいでしょう。私が言ったように、彼は常に非常に啓発的です。

一部の人々はさらに先に進み、会社は完全に後退するべきだと述べています。

1. プレスリリースを書く
2. よくある質問を書く
3. カスタマーエクスペリエンスを定義する
4. ユーザーマニュアルを書く
5. プログラミングを開始

http://www.allthingsdistributed.com/2006/11/working_backwards.htmlを ご覧ください

最初に完全なコードドキュメントを書くことは、おそらくやり過ぎであり、ウォーターフォールの方法論を幾分連想させます。しかし、より実用的なアプローチが最初にREADMEを書くことであることがわかりました。その理由は次のとおりです。

READMEは、プロジェクトのすべての詳細を文書化するものではありません。代わりに、通常、次の情報が含まれています。

1. 説明：短い「セールスピッチ」。読者に読み続ける理由を伝えます。
2. 簡単な例：説明をサポートするための短いコードスニペットまたはスクリーンショット。
3. クイックスタート：開始方法、インストール手順、その他の例。
4. その他のドキュメント：完全なドキュメントおよび詳細情報へのリンク。
5. プロジェクトの構成：作成者、貢献方法、バグの報告方法。
6. 法的通知：ライセンス、著作権、およびその他の法的詳細。

「セールスピッチ」を前もって書くことで、このプロジェクトが存在する理由と開発者がそれを使用する理由について明確にする必要があります。プロジェクトを説明するために完全な文章を書くだけの行為は、多くの場合それをより良く変えます。あなたはそれをよりよく理解し、新しいアイデアを開発し、潜在的な問題を発見します。また、優れた優先順位付けツールでもあります。「売り込み」にあるものはすべて必須です。

「クイック例」と「クイックスタートガイド」により、ユーザーの観点から主要なユースケースを考えるように強制されます。コードを書く前に-実装の詳細と厳しい締め切りに行き詰まる前にこれを行うと、はるかにきれいなAPIと設計につながることがわかりました。覚えておいてください：プログラムは人々が読むために書かれるべきであり、偶然にマシンが実行するためだけに作られるべきです（SICP）。

「詳細なドキュメント」では、後で行うために詳細なドキュメントが必要な部分の概要を作成します。「プロジェクトの編成」により、プロジェクトの誰が作業するのか、コーディングのプラクティスを把握できます。「法的通知」...まあ、それらも邪魔にならないかもしれません。

この基本的なREADMEが準備できたら、ディスカッション、設計レビュー、作業の分割、およびプロジェクトの計画に役立つドキュメントが手に入ります。プロジェクトで作業するときは、READMEで頻繁にチェックして、まだ順調に進んでいることを確認してください。また、READMEと「その他のドキュメント」を段階的に更新することは、コードが完了するとすべてのドキュメントが完成することを意味します。

詳細については、次を確認してください。

1. Readme駆動型開発
2. 最も重要なコードはコードではありません
3. あなたは文書化するものです

クラスの相互作用について考えたくないのはなぜですか？なぜそれが悪いのですか？クラスが何であるかを知る前に、実際に相互作用について考えます。そのようにして、クラスは自分自身を識別します。

コードを作成する前に、何をするつもりなのかをある程度知っている必要があります。問題は常に、あなたが書いたものと同期してコーディングしたものをどのように保つかです。試さないと言う人もいれば、最初のドキュメントを忘れてコメントを続けると言う人もいます。もちろん、コードは常に標準的なソースです。問題は、後で来る人やコードを使用する人のためにコードが何をするかを文書化する価値があるかどうかになります。誰でも関数の機能を理解できます。作家の仕事は、誰かが1時間で理解できることを5分で理解できるようにすることです。デルタを合計して、パスを決定します。