オープンソースプロジェクトのコード概要がないのはなぜですか？[閉まっている]

そこには非常に複雑なオープンソースプロジェクトがあり、そのうちのいくつかに私は貢献できると思います、そして私はできると思いますが、単一の理由でコードへの1行を変更するために、エントリーに対する障壁が高すぎます大きなプロジェクトをすべて理解する必要があります。

すべてのコードを読む必要はありません（読んでも十分ではありません）、すべての単一行が行うこととその理由をすべて理解する必要があります。コードはおそらくモジュール化され、コンパートメント化されているためです。その場合でも、プロジェクトの概要を取得して、モジュールの場所、あるモジュールが他のモジュールとインターフェイスする場所、各モジュールが正確に何をするのか、なぜなのか、これらの各イベントがどのディレクトリとファイルで発生するのかを知る必要があります。

私はこのコードの概要を、オープンソースプロジェクトがウェブサイトや外部の人にコードを説明するドキュメントに含めることができるセクションの名前として呼んでいます。私はそれが恩恵を受けるだろうと思う潜在的な貢献者を、彼らは実際、構築できる場所を識別することができるだろうとして、主コーダーは、彼らがすべてを書きながら、彼らの心を再編成することができるだろうとして、関与を、そして役立つだろうユーザーを、彼らは同じように、彼らが経験するバグを理解し、より良い報告をする助けになり、貢献者になることさえあります。

しかし、これらの「コードの概要」の1つを見たことはありません。どうして？これらのようなものがあり、私はそれらを見逃していますか？私が説明しているのと同じ仕事をするものは？または、これは完全に役に立たないアイデアですか？

そのようなドキュメントを作成して維持するのは余分な労力であり、関連する利点を理解していない人が多すぎるためです。

多くのプログラマーは優れたテクニカルライターではありません（多くのプログラマーはそうですが）。人間が消費するためだけにドキュメントを書くことはめったにないので、練習もできず、好きでもありません。コードの概要を書くことは、コーディングに費やすことができない時間を要します。プロジェクトの最初の利点は、「コードの本当にきちんとした説明がある！」ではなく、「3つのエンコーディングバリアントをすべてサポートします」と言えば常に大きくなります。このようなドキュメントがより多くの開発者を引き付け、長期的にはより多くのコードが記述されるという概念は、彼らにとってまったく異質ではありませんが、不確実なギャンブルとして認識されています。このテキストは、共同編集者を捕まえることとそうでないことの違いを本当にもたらすのでしょうか？今すぐコーディングを続けると、 このことを成し遂げてください。

コード概要ドキュメントは、人々を防御的に感じることもできます。正当化する必要性を感じずに上位レベルの決定を記述することは困難であり、実際に書かれたときに「十分に聞こえる」理由なしに人々が決定を下すことは非常に多い。前述のものに関連する効果もあります。変更するコードに合わせてテキストを更新すると追加の労力が発生するため、これによりコードの大幅な変更が妨げられる可能性があります。時々、この安定性は良いことですが、コードが本当に中間レベルの書き換えを必要とする場合、それは責任に変わります。

乾燥した、厳しい真実？

プロジェクトはそれなしで行うことができるため、ドキュメントは作成されません。

オープンソースプロジェクトでさえ、しばしば厳しい競争に直面しています。そのようなプロジェクトのほとんどは、大きな肩から始まるのではなく、明るいアイデアから始まります。

そのため、無料で協力することを申し出たとしても、人間のドキュメンタリーを雇う時間と費用を支払う余裕はありません。文書化されたプロジェクトである事実は、通常、最初にいくつかの最初の反復を経ています。多くの場合、1〜3で始まり、5人の男が斬新なアイデアを書き留め、概念実証として世界に公開します。アイデアが良ければ、「フォロワー」が追加するかもしれません。彼らは拡張機能、新しいオプション、翻訳を求め始める傾向があります。

すべてのオープンソースプロジェクトがこのフェーズを超えるわけではなく、「クリティカルマス」を破るプロジェクトだけが公共の関心を引くのに必要です。さらに、最初の開発者の1人は、「大きく、遠くまで考え」、拡張などを計画する必要があります。彼はプロジェクトの「エバンジェリスト」になることもあれば、「プロジェクトマネージャー」になることもあります（場合によっては、異なる人々）。これは、概念実証から業界で確立された現実まで、プロジェクトを立ち上げるために必要なステップです。

それでも、プロジェクトマネージャーはドキュメントを作成しないことを選択できます。

動的で成長しているプロジェクトはスローダウンし、ドキュメントは本当にコードより遅れますが、翻訳、オプション、プラグインマネージャーを実装するために非常にハードに強化されます...

通常起こることは：

1. プロジェクトの概要と目的地（有名な「ロードマップ」）についての簡単な紹介文書が作成されます。
2. 可能であれば、APIが開発され、そのAPIが基礎となるコードの大部分に対して「文書化されたコード」として選出されます。
3. 特にAPIだけでなく、他のコードも再フォーマットされ、「PHPdoc」/「Javadoc」などの特別なコメントが追加されます。彼らは費やした時間と報酬の間にまともな妥協を提供します：控えめなプログラマーでさえ、通常、自分の機能を説明する1つのライナーを書く方法を知っており、パラメータも同様に「自動」文書化され、全体が関連するコードに関連付けられているため、文書化を回避します」非同期」と遅れる開発。
4. ほとんどの場合、フォーラムが作成されます。これは、エンドユーザーとプログラマーが互いに（そして、おそらく「開発者専用」サブフォーラムで、ピア間で）話すことができる強力なソーシャルメディアです。これにより、コミュニティが作成した多くの知識がゆっくりと出現し、統合されます（開発者チームに負担をかけないでください）FAQとHOWTO。
5. 本当に大規模なプロジェクトでは、Wikiも作成されます。「大規模プロジェクト」と述べるのは、多くの場合、ウィキを作成するのに十分なフォロワーがいる（開発者が）、実際に「裸の骨」を超えて埋める（コミュニティが行う）ためです。

あなたが説明するような概要ドキュメントは、商業プロジェクトでもまれです。開発者にとってほとんど価値のない追加の努力が必要です。また、開発者は、本当に必要な場合を除き、ドキュメントを作成しない傾向があります。一部のプロジェクトでは、テクニカルライティングが得意なメンバーがいて、その結果、優れたユーザードキュメントが用意されています。開発者向けドキュメントが存在する場合、コードの変更を反映するために更新されることはほとんどありません。

よく組織されたプロジェクトには、比較的自明のディレクトリツリーがあります。一部のプロジェクトでは、この階層および/または選択された理由を文書化します。多くのプロジェクトは比較的標準的なコードレイアウトに準拠しているため、1つを理解すれば、同じレイアウトを使用する他のプロジェクトのレイアウトを理解できます。

コードの行を変更するには、周囲のコードについての限られた理解が必要です。コードベース全体を理解する必要はありません。破損している機能の種類について合理的な考えを持っている場合は、かなり迅速にディレクトリ階層をナビゲートすることができます。

コードの行を変更するには、その行が見つかったメソッドを理解する必要があります。メソッドの予想される動作が何であるかを理解している場合、修正変更または機能の拡張を行うことができるはずです。

スコープを提供する言語の場合、プライベートスコープメソッドをリファクタリングできます。この場合、呼び出し元とリファクタリングメソッドを変更する必要があります。これには、コードベースのより広い、しかしまだ制限された理解が必要です。

そのような変更を行う方法の例については、私の記事「tinycaにSHA-2を追加する」を参照してください。インターフェースの生成に使用されるコードについての理解は非常に限られています。

これらのようなものがあり、私はそれらを見逃していますか？私が説明しているのと同じ仕事をするものは？

The Architecture of Open Source Applicationsと呼ばれる優れた本があり、さまざまな有名なオープンソースソフトウェアプロジェクトの詳細な説明を提供しています。ただし、それがあなたが想像している役割を正確に満たしているかどうかはわかりません（ただし、そこに役立つと確信しています）。

なぜなら、オープンソースのテクニカルライターよりもはるかに多くのオープンソースのプログラマーがいるからです。

ドキュメントは最新の状態に保つためにメンテナンスと時間がかかります。ドキュメントがかさばるほど、より多くの情報が必要になります。そして、コードと同期していないドキュメントは役に立たないというよりも悪いです。それは明らかにするのではなく、誤解を招き、隠します。

文書化されたコードベースは、文書化されたコードベースよりも優れていますが、最初にコードを記述する限り、文書化は簡単に行えます。あなたの質問は、よく文書化されたコードベースを持っている方が良いですか、それとも2倍のコードベースを持っている方が良いですか？コードが変更されるたびにドキュメントを最新の状態に維持するためのコストは、追加の開発者の貢献に値するものですか？

配送コードが優先されます。コードの出荷以外に費やす労力を減らすと、コードの出荷頻度が高くなり、リソースがなくなる前に出荷される可能性が高くなります。

これは、輸送問題以外のことを意味するものではありません。ドキュメンテーションはプロジェクトに価値を追加します。プロジェクトが十分に大きい場合、他の開発者を追加する相互接続コストはドキュメンターを追加するよりもはるかに高くなる可能性があります。また、前述のように、ドキュメントはプロジェクトへの投資を増やすことができます（新しいプログラマーが参加しやすくすることにより）。

しかし、成功のように売れるものはありません。機能していないプロジェクトや面白いことをしているプロジェクトも、開発者を惹きつけることはめったにありません。

コードベースの文書化は、メタワークの一形態です。多くの時間を費やして、あまり価値のないコードベースを説明する派手なドキュメントを作成したり、コードベースの消費者が望むものを作成してコードベースに価値を持たせることができます。

時々物事を難しくすると、タスクを実行する人が良くなります。プロジェクトへのより高いコミットメント（アーキテクチャの学習に何時間も費やす）か、スキルバイアス（既に関連技術の専門家である場合は、スピードアップが速くなるため）不足の障壁このようなドキュメントの重要性はそれほど高くありません。したがって、チームに参加する専門家が増え、初心者が少なくなります。

最後に、上記の理由により、現在の開発者はコードベースの専門家である可能性があります。そのような文書を書くことは助けにはならない彼らは、彼らがすでに知識を持っているとして、それだけで他の開発者を助け、多くのコードベースを理解しています。オープンソース開発の多くは、開発者がコードで持つ「悩み」に基づいています。開発者がほとんどかゆいことを知っていることをすでに説明しているドキュメントがないことです。

余分な努力であることに加えて、いくつかのオープンソースプロジェクトは、メンテナーのためにフリーランスの仕事を得るために（何かを実装したり、トレーニングをしたりするために）意図的にドキュメントを壊しています。コードの概要がないだけでなく、APIとチュートリアルが悪いか、多くのことが欠けています。

非常に人気のある名前を挙げると、bluezです。近くのデバイスをスキャンする以外に、良いチュートリアルを見つけてください。