オープンソースプロジェクトのコードの概要がないのはなぜですか？
非常に複雑なオープンソースプロジェクトが世の中にあり、それらのいくつかに対しては、私はいくつかの貢献をすることができると思いますし、できればいいのですが、1つの理由でエントリへの障壁が高すぎます。あなたはそれをすべて理解しなければならない大きなプロジェクト。
すべてのコードを読む必要はありません（読んでも十分ではありません）。コードはおそらくモジュール化されており、区分化されているため、抽象化されているため、それでも、プロジェクトの概要を取得する必要があるため、場所モジュールですここで1つのモジュールを他のモジュールとインターフェースします正確に各モジュールは、whyを実行し、どのディレクトリとファイルでこれらのことが発生しています。
私はこれをコードの概要と呼んでいます。これは、オープンソースプロジェクトがWebサイトまたはドキュメントに外部の人にコードを説明するセクションにある可能性があるためです。 潜在的な貢献者が彼らが彼らが構築できる場所、実際のを特定することができるので、それは利益になると思います主要なコーダーが関与し、彼らはすべてを書いている間に彼らの心を再編成し、usersを助けることができるので、彼らは彼らが経験するバグを理解し、よりよく報告するのに役立つので、そしておそらく貢献者になることさえあるでしょう。
しかし、それでも、これらの「コードの概要」の1つを見たことはありません。どうして？このようなものはありますか、私はそれらを逃していますか？私が説明しているのと同じ仕事をするもの？それとも、私を除いて誰もが数千行のコードを持つプロジェクトを簡単に理解できるので、これは完全に役に立たないアイデアですか？
そのような文書を作成して維持するのは余分な労力であり、あまりに多くの人々が関連する利点を理解していないからです。
多くのプログラマーは優れたテクニカルライターではありません（多くのプログラマーはそうですが）。彼らはめったに人間が消費するためにドキュメントを書くことはめったにないので、彼らには練習がなく、それをするのが好きではありません。コードの概要の記述には、コーディングに費やすことができない時間がかかります。プロジェクトのinitialの利点は、「3つのエンコーディングバリアントすべてをサポートしている」ではなく、「本当にコードのきちんとした説明！」そのようなドキュメントがより多くの開発者を引き付け、長期的にはより多くのコードが書かれるという考えは、正確にはforeignではありませんが、不確実なギャンブルとして認識されます。このテキストは本当に共同編集者を引っ掛けるかどうかの違いを作るでしょうか？私がコーディングを続ければ今のところ、確かにこのことを成し遂げるでしょう。
コード概要ドキュメントは、人々を守備的に感じることもあります。正当化する必要性を感じずに、より高いレベルの決定を説明することは困難であり、実際に自分で書いたときに「十分に聞こえる」理由なしに決定を下すことがよくあります。前述のものに関連する影響もあります。変更するコードに合わせてテキストを更新すると追加の作業が発生するため、コードへの変更を一掃することを妨げることがあります。場合によっては、この安定性が良いこともありますが、コードで中間レベルの書き換えが本当に必要な場合は、責任が生じます。
辛くて厳しい真実？
プロジェクトはそれなしで行うことができるので、ドキュメントは作成されません。
オープンソースプロジェクトでさえ、しばしば厳しい競争に直面しています。そのようなプロジェクトのほとんどは、大きな肩から始めるのではなく、明るいアイデア、しばしば一人の明るいアイデアから始まります。
そのため、無料で協力することを申し出たとしても、人間のドキュメンターを雇う時間と費用をかける余裕はありません。文書化されたプロジェクトは、実際には通常、最初にいくつかの最初の反復を経ています。多くの場合、1〜3人、おそらく5人が斬新なアイデアを書き留め、それをコンセプトの証明として世界に公開します。アイデアが良かった場合、「フォロワー」が追加する可能性があり、拡張機能、新しいオプション、翻訳を求め始める傾向があります...この時点で、コードはまだプロトタイプであり、通常はハードコードされたオプションとメッセージが含まれています。
すべてのオープンソースプロジェクトがこのフェーズを超えるわけではなく、「重要な質量」を打破するプロジェクトのみが、公共の関心を引き付けるために必要です。さらに、最初の開発者の1人は、「大きく、遠くまで考え」、拡張などを計画する必要があります。彼はプロジェクトの「エバンジェリスト」になることもあれば、「プロジェクトマネージャー」になることもあります（別の人の場合もあります）。これは、概念実証から業界で確立された現実まで、プロジェクトを立ち上げるために必要なステップです。
それでも、プロジェクトマネージャーはドキュメントを作成しないことを選択できます。
翻訳、オプション、プラグインマネージャーを実装することは非常に困難ですが、動的で成長するプロジェクトは速度が低下し、ドキュメントはコードに遅れをとります。
通常何が起こるか：
- プロジェクトとは何か、どこに行くのかについての簡単な紹介ドキュメントが作成されます（有名な「ロードマップ」）。
- 可能であれば、APIが開発され、基礎となるコードの大部分から「ドキュメント化されたコード」として選ばれます。
- 特に、APIだけでなく他のコードも再フォーマットされ、「PHPdoc」/「Javadoc」などの特別なコメントが追加されます。彼らは費やした時間と報酬の間でまともな妥協を提供します：ささやかなプログラマーでさえ、彼の機能を説明する1つのライナーを書く方法を通常知っています。非同期化」と遅れる動作の開発。
- ほとんどの場合、フォーラムが作成されます。これは、エンドユーザーとプログラマーが互いに（そして、おそらく「開発者のみ」のサブフォーラムで）仲間同士で話すことができる強力なソーシャルメディアです。これにより、多くの知識が徐々に出現し、コミュニティによって統合されます（読む：開発者チームに重きを置かない）FAQとHOWTO。
- 本当に大きなプロジェクトでは、wikiも作成されます。私は「大規模プロジェクト」と述べています。彼らは、多くの場合、Wikiを作成するのに十分なフォロワーがいるため（開発者が行う）、実際に「ベアボーン」を超えてそれを埋める（コミュニティーが行う）ためです。
あなたが説明するような概要文書は、商業プロジェクトであってもめったにありません。それらは開発者にとってほとんど価値のない追加の努力を必要とします。また、開発者は本当に必要でない限り、ドキュメントを書かない傾向があります。一部のプロジェクトは、テクニカルライティングが得意なメンバーがいて幸運であり、その結果、優れたユーザードキュメントを持っています。開発者用ドキュメントが存在する場合、コードの変更を反映するために更新されることはほとんどありません。
うまく整理されたプロジェクトには、比較的自明のディレクトリツリーがあります。一部のプロジェクトは、この階層および/またはそれが選択された理由を文書化します。多くのプロジェクトは比較的標準的なコードレイアウトに従っているため、1つを理解すれば、同じレイアウトを使用する他のプロジェクトのレイアウトを理解できます。
コードの行を変更するには、周囲のコードをある程度理解する必要があります。コードベース全体を理解する必要はありません。壊れている関数の種類について合理的な考えがある場合、ディレクトリ階層をすばやく移動できることがよくあります。
コードの行を変更するには、その行が含まれているメソッドを理解する必要があります。メソッドの予想される動作が何であるかを理解している場合は、機能を修正または拡張することができます。
スコーピングを提供する言語の場合、プライベートスコープメソッドをリファクタリングできます。この場合、呼び出し元とリファクタリングメソッドを変更する必要がある場合があります。これには、コードベースのより広い、しかしまだ限られた理解が必要です。
そのような変更を行う方法の例については、私の記事 tinycaへのSHA-2の追加 を参照してください。インターフェイスを生成するために使用されるコードについて、私は非常に限られた理解しか持っていません。
このようなものはありますか？私が説明しているのと同じ仕事をするもの？
著名なオープンソースソフトウェアプロジェクトのさまざまな詳細な説明が記載された、優れた本 The Architecture of Open Source Applications があります。ただし、それがあなたが想像している役割を完全に満たすかどうかはわかりません。その主な対象者は、本で取り上げられているプロジェクトへの新しい貢献者ではなく、独自のアプリケーションを作成するときに従うパターンを探している開発者を対象としているためです。 （私はそれが役に立つかもしれないと確信していますが）。
なぜなら、オープンソースのテクニカルライターよりもはるかに多くのオープンソースのプログラマーがいるからです。
ドキュメントを最新の状態に保つには、メンテナンスと時間がかかります。ドキュメンテーションがかさばるほど、それだけ多くの時間がかかります。そして、コードと同期していないドキュメントは、役に立たないよりも悪いです。それは明らかにするのではなく、誤解を招き、隠蔽します。
十分に文書化されたコードベースは、1つ少ない文書化よりも優れていますが、最初にコードを記述している限り、簡単に文書化できます。だからあなたの質問は、十分に文書化されたコードベース、または2倍の大きさのコードベースを持っている方が良いですか？追加の開発者の貢献に見合う価値のあるコードの変更があった場合にドキュメントを最新の状態に保つためのコストはありますか？
配送コードが優先されます。コードの配布以外に費やされる労力を削減すると、コードの配布頻度が高くなり、リソースが不足する前に出荷される可能性が高くなります。
これは、出荷以外のことが重要であることを意味しません。ドキュメンテーションはプロジェクトに付加価値を与えます。プロジェクトが十分に大きい場合、別の開発者を追加する相互接続コストは、ドキュメンタリーを追加するよりもはるかに高くなる可能性があります。また、前述のように、ドキュメントはプロジェクトへの投資を増やすことができます（新しいプログラマーが参加しやすくなるため）。
しかし、成功するほど売れるものはありません。機能していないプロジェクトや興味深いことをしていないプロジェクトも、開発者を魅了することはめったにありません。
コードベースのドキュメントは、メタワークの一種です。多くの時間を費やして、価値のないコードベースを説明する豪華なドキュメントを作成したり、コードベースの利用者が望むものを作成してコードベースに価値を持たせたりすることに時間を費やすことができます。
時には物事を難しくすることで、その仕事をより上手くできる人がいます。プロジェクトへの取り組みの度合いが高いため（アーキテクチャの学習に何時間も費やす）、またはスキルの偏りがあるため（すでに関連技術の専門家である場合は、速度を上げることがより速くなるため、不足の障壁となります）そのようなドキュメントの重要性は低くなります。したがって、より多くの専門家がチームに参加し、初心者が少なくなります）。
最後に、上記の理由により、現在の開発者はコードベースの専門家である可能性があります。そのようなドキュメンテーションを作成しても役に立ちませんthemコードベースを十分に理解します。彼らはすでに知識を持っているため、他の開発者を助けるだけです。オープンソース開発の多くは、開発者がコードを使って「かゆみを掻く」ことに基づいています。開発者が知っていることをめったにかゆくしないことをすでに述べているドキュメントの欠如。