コードベースでファイルを適切に整理する方法と騒乱を避ける方法

大規模なコードベースの組織とメンテナンス：メインライブラリ、データ、UI、ドキュメントとWiki、テスト、レガシーコンポーネント、サードパーティコンポーネント...このすべてのコンテンツの順序を追跡および維持する方法は？コードベース内のファイルの構成は、難しい作業になる可能性があります。

心配しないでください - 私たちはそれをすることができます！この記事では、中小プロジェクトに最も一般的に使用されているシステムをレビューし、フォローが簡単なベストプラクティスを提供します。

キーポイント

コードベースでファイルを整理することは、将来コンテンツにアクセスして確認する必要がある場合に問題を軽減し、時間を節約できます。ファイルの命名、プロジェクトのドキュメント処理、および効果的なワークフローの組織に関する基本的なルールを確立することが非常に重要です。

• 各ソフトウェアプロジェクトには、readme、changelog、コピーライセンス、.gitignoreファイルが必要です。プロジェクトの状況に応じて、著者、バグ、寄稿/ハッキング、FAQ、インストール、ニュース、ありがとう、TODO/ロードマップ、バージョン/リリースなどの他のファイルも含めることができます。
• ファイルはコンポーネントまたはサブシステムのフォルダーに編成する必要がありますが、物事を管理しやすくするためにディレクトリを作成する必要があります。データ、バイナリファイル、設定などの特定のファイルは、プロジェクトから除外する必要があります。
• 文書化の鍵は、組織の一貫性にあります。それがディレクトリやファイルの命名であろうと、プロジェクトの構造であろうと、一貫性を維持することで、コードベースのナビゲートと理解が容易になります。
なぜわざわざ？

プロジェクト管理関連のタスク（文書化、ソフトウェアの提出、展開）と同様に、意識的でプログラム的なアプローチから大きな恩恵を受けるでしょう。

これは現在の問題を軽減するだけでなく、コンテンツに迅速にアクセスして将来レビューする必要がある場合に、あなたとあなたのチームの貴重な時間を節約します。

今すぐ書いているものの関数名を間違いなく思い出すことができ、編集する必要があるファイルをすばやく見つけて、何が機能し、何がそうでないか、またはあなたがどう思うかを明確に伝えることができます。しかし、昨年働いたプロジェクトについて同じことを言うことができますか？

認めましょう：ソフトウェアプロジェクトは、数か月または数年の不活性性が続く場合があります。シンプルなreadmeファイルは、同僚や将来のあなたのために多くのことをすることができます。ただし、プロジェクトを構築し、ファイルに名前を付けるためのいくつかの基本的なルールを構築し、プロジェクトのドキュメントを処理し、ある程度時間のテストに耐える効果的なワークフローを整理できる他の方法を考えてみましょう。

物事を理解する

組織プロジェクトのドキュメントの「ベースライン」を確立します。これは、ソフトウェア開発の範囲内で多くの状況で私たちに役立つロジックです。

コードベースの変更を正しく送信することに関するルールと同様に、これらはいずれも石に設定されておらず、その価値の観点から、あなたとあなたのチームは異なるガイド原則を提案するかもしれません。とにかく、一貫性はゲームの名前です。ルールが何であるかを理解し、議論または議論していることを確認し、コンセンサスに到達した後にそれらに従ってください。

必要なドキュメント

これは、ほとんどすべてのソフトウェアプロジェクトが必要なファイルの参照リストです。

readme：これは、Githubがソースツリーの下で提示するものです。これは、プロジェクトの内容、ファイルの整理方法、および詳細情報を見つける場所を説明するのに役立ちます。
• changelog：各バージョンまたはリビジョンの新しい、変更された、または無効化されたコンテンツをリストします。通常は便利なため、反順序で順序で順序付けます（最新の変更は最前線にあります）。
コピーライセンス：ソフトウェアをカバーするライセンスの全文を含むファイル、および必要に応じて、他の著作権情報（サードパーティライセンスなど）。
.Gitignore：Gitを使用していると仮定して（これを使用する可能性が最も高い）、これはリポジトリと同期していないファイルを伝えるために必要です。 （.gitignoreの詳細については、ジャンプスタートGitのGetting Gute Guide and Documentationを参照して、いくつかのアイデアのために.Gitignoreテンプレートの便利なコレクションをご覧ください。）
• サポーター

プロジェクトの状況に応じて、他のドキュメントを含めることを検討することもできます。

著者：コードの作成に関与する人の帰属。

バグ：新たに発見されたエラーを報告するための既知の問題と指示。

• 貢献/ハッキング：潜在的な貢献者のためのガイド。特にオープンソースプロジェクトに役立ちます。
• FAQ：あなたはすでにこれが何であるかを知っています。 ;）
• インストール：さまざまなシステムにソフトウェアをコンパイルまたはインストールする方法に関する指示。
• ニュース：Changelogファイルに似ていますが、開発者ではなくエンドユーザーの場合。
• ありがとう：ありがとう。
• TODO/ロードマップ：計画されている今後の機能のリスト。
• バージョン/リリース：現在のバージョン番号または配布名を記述するコードの行。
• コンポーネントまたはサブシステムのフォルダー
しばしば、単一の概念に結合できる一連の関数に遭遇します。

いくつかの例は次のとおりです

Internationalization（I18N）およびローカリゼーション（L18N）

認証モジュール

サードパーティアドオン
一般的なツールとクロンの割り当て
ユーザーインターフェイス（UI）およびグラフィックユーザーインターフェイス（GUI）
• これらすべては、単一の「コンポーネント」または「サブシステム」ディレクトリに編成できますが、クレイジーではありません！
• ルートディレクトリ（メインコンポーネントがここにある）であろうと再帰的に（各ディレクトリ内）を管理しやすくするために、ディレクトリの作成を制限したいと考えています。それ以外の場合は、よく組織化されたディレクトリでファイルを閲覧するために多くの時間を費やすことになります。

ソースツリーからこれらを除外してください

プロジェクトをきちんと整然としていることを望んでいますが、プロジェクトから完全に除外したい文書がいくつかあります。

データ。 CSVファイルなどのソースツリーにデータ/ディレクトリを使用するように誘惑される場合があります。特に、数キロバイトしか使用しない場合。しかし、彼らがメガバイトやギガバイトを取り上げたらどうでしょうか（最近は珍しいことではありません）？あなたは本当にあなたのコードベースと同じようにこれらをコードに送信したいですか？いいえ。

バイナリファイル。ビデオレンダリングまたはコンパイルされた実行可能ファイルをソースコードの隣に配置することは望ましくありません。これらは開発ファイルではなく、ここにはまったく属していません。データファイルのように、彼らは最終的に多くのスペースを占有することになります。

設定。これは別の大きなタブーです。コードベースに資格情報、パスワード、またはセキュリティトークンを配置しないでください。ここではこの問題の解決策をカバーすることはできませんが、Python開発者の場合は、Python Decoupleの使用を検討してください。

ケース1：Webアプリケーション

Webアプリケーションを考えてみましょう。デスクトップであろうとモバイルデバイスであろうと、ブラウザを介してアクセスできるWebサーバーで実行されるソフトウェアです。また、ある種のプレミアムサービスにアクセスするためのメンバーシップを提供するWebアプリケーションであると仮定します。おそらく排他的なレポート、旅行のヒント、またはビデオライブラリです。

ファイル構造

<code>├── .elasticbeanstalk
├── .env
├── billing
├── changelog.txt
├── locale
│   ├── en
│   └── zh_Hans
├── members
├── readme.txt
├── static
│   ├── fonts
│   ├── images
│   ├── javascript
│   └── styles
├── templates
│   ├── admin
│   └── frontend
├── todo.txt
└── tools</code>

分析

これは、2つの言語（英語と単純化された中国語（Locale Directory）をサポートする基本的なWebアプリケーション構造です。請求書とメンバーの2つの主要なコンポーネントもあります。

ウェブサイトの開発にもう少し精通している場合、静的フォルダーとテンプレートフォルダーの内容は馴染みがあるかもしれません。おそらく、唯一の珍しい要素は、Amazon Web Services（AWS）の展開ファイルを保存するElasticBeanStalkと、データベース資格情報などのプロジェクトの設定のみをオンプレミスのみ保存するElasticBeanStalkです。 ReadmeやTodoなど、残りはそれについて議論しました。 ツールディレクトリは興味深いディレクトリです。ここでは、たとえば、スクリプトを保存し、データベースをトリミングしたり、支払いステータスをチェックしたり、静的ファイルをキャッシュにしたりすることができます。基本的には、アプリケーション自体ではなく、機能するのに役立ちます。

命名に関して、画像ディレクトリを画像/またはimg/に名前を付けるか、スタイルディレクトリにスタイル/またはcss/に名前を付けるか、javascript/ディレクトリにjs/に名前を付ける場合、違いはありません。主なことは、構造が論理的であり、長い説明的な名前であろうと短い名前であろうと、常に特定の慣習に従うことです。

ケース2：デスクトップアプリケーション

コンピューターにダウンロードしてインストールできるアプリケーションを考えてみましょう。また、アプリケーションにCSVファイルなどの入力が必要であると仮定し、一連のレポートをレンダリングします。

この例では、ソースツリーをわずかに大きくします。

ファイル構造

分析

UI/フォルダーは、基本的にアプリケーションの中核です。サブフォルダーの名前はほとんど自明です（もう1つの良い習慣）。 Webアプリケーションの例とは異なり、ここでは略語名（JavaScriptの代わりにJSなど）を選択しました。繰り返しますが、本当に重要なのは、プロジェクト全体で一貫しているということです。

<code>├── .gitignore
├── data
├── doc
├── legacy
│   ├── dashboard
│   ├── img
│   └── system
├── LICENSE
├── README
├── tests
├── thirdparty
├── tools
│   ├── data_integration
│   └── data_scraping
├── ui
│   ├── charts
│   ├── css
│   ├── csv
│   ├── dashboard
│   ├── img
│   │   └── icons
│   ├── js
│   ├── reports
│   └── summaries
├── VERSION
└── wiki</code>

先ほど、ソースツリーからデータファイルを除外することをお勧めしますが、そこにはデータ/フォルダーがあります。これはどうやって起こるのでしょうか？このツリーは、アプリケーションを適切にテストするためにデータを必要とする開発者のボックスと考えてください。ただし、.gitignoreファイルに設定されたルールに従って、データはまだリポジトリの同期から外れていません。

レガシー/フォルダーは、中止されようとしているアプリケーションの一部に使用されますが、それでも新しいシステムに完全にリファクタリングされるまで便利になる可能性のある機能を提供します。したがって、古いコードを現在のコードから分離する良い方法を提供します。

ここに新しい追加は、テスト/であり、ユニットテストを使用して品質を確保する場所と、ソフトウェアが必要とする外部ライブラリを保存する場所であるThirdParty/を提供します。

doc/およびwiki/フォルダーがあることに注意してください。これは複製のように見える場合があります。ただし、エンドユーザー用のドキュメントフォルダーと開発チームのWikiを持つことも完全に可能です。

要約

繰り返す価値のある良いニュースは次のとおりです。たとえあなたが一人で働いていても、あなたは整理されなければなりません。この記事では、アプリケーションのファイルの数が増えるにつれて混乱を防ぐために、すぐにワークフローへの適用を開始できるアイデアがあることを願っています。

前述のように、ガイドラインは（ほぼ）すべてのプロジェクトが異なっており、チームもそうであるため、ガイドラインは時々変わる可能性があります。理想的には、あなたまたはあなたのチームはプロジェクトの構築方法を決定します - この構造の理由を説明するために小さなドキュメントを追加してください - そして、あなたはこれらのルールに固執します。

ここでの多くのガイドラインでは、ファイルに名前を付けるためにダッシュまたはアンダースコアを選択するかどうかは関係ないことを忘れないでください（多くのトピックのいずれかを選択してください）。キーは一貫性です。

さらに読み取り

「Python Getting Guide Guide」のプロジェクト構造。
• UX Collectiveからプロジェクトフォルダー構造を管理するためのシステム方法。
• 効果的なプロジェクト管理：伝統的、アジャイル、極端な、ハイブリッド
• プロジェクトドキュメントの整理（FAQ）
についてのFAQ

プロジェクトドキュメントを構造化された方法で整理する利点は何ですか？

構造化された方法でプロジェクトドキュメントを整理することには多くの利点があります。まず、コードの読みやすさと保守性を向上させます。ファイルが論理的に整理されている場合、開発者は既存の機能を破ることなくコードベースを理解し、変更を加えることが簡単です。第二に、チームワークを強化します。複数の開発者が同じプロジェクトで作業すると、よく組織化されたファイル構造により、誰もが特定のスニペットを見つける場所を知っていることが保証されます。最後に、開発プロセスを高速化します。開発者は、ファイルの検索に費やす時間が少なく、コードの書き込みと最適化に時間がかかります。

プロジェクトファイルの最適な構造を決定する方法は？

プロジェクトファイルの最適な構造は、プロジェクトの性質と複雑さに依存します。小規模なプロジェクトでは、単純なディレクトリ構造で十分かもしれません。ただし、複数のコンポーネントを備えた大規模なプロジェクトの場合、より複雑な構造が必要になる場合があります。使用しているプログラミング言語、使用しているフレームワークまたはライブラリ、チームの好みなどの要因を考慮してください。プロジェクトが成長するにつれて開発できるように、構造を柔軟にすることが重要です。

コードを整理するための一般的な戦略は何ですか？

コードを整理するためのいくつかの戦略があります。一般的な方法は、機能ごとにファイルをグループ化することです。これは、特定の関数に関連するすべてのファイルが同じディレクトリに保存されることを意味します。別の方法は、CSS、JavaScript、HTMLファイルの分割など、タイプごとにファイルをグループ化することです。一部の開発者は、両方の戦略の要素を組み合わせて、ハイブリッドアプローチを使用することを好みます。重要なのは、プロジェクトとチームにとって理にかなっている戦略を選択することです。

コードベースが成長するにつれて、組織を維持する方法は？

コードベースが成長するにつれて、ファイル構造を定期的に確認およびリファクタリングすることが重要です。これには、大規模なファイルをより小さく、より管理しやすいファイルに分割するか、プロジェクトの現在の状態をよりよく反映するためにディレクトリを再編成することが含まれます。自動化ツールは、不器用になったり、維持が困難になったりするコードベースの領域を特定するのに役立ちます。定期的なコードレビューは、新しいコードが確立されたファイル構造に適合するようにするのにも役立ちます。

ファイル組織で命名規則がどのような役割を果たしていますか？

命名規則は、ドキュメント組織において重要な役割を果たします。一貫性のある説明的なファイル名により、各ファイルに何が含まれているかを理解しやすくなります。これにより、特に大規模なプロジェクトを扱ったり、チームと協力したりする場合、開発プロセスを大幅に高速化できます。命名規則は、プロジェクトの開始時に合意されるべきであり、常に一貫性を保ちます。

すべてのチームメンバーが私のファイル組織戦略に従うことを確認する方法は？

すべてのチームメンバーがファイル組織ポリシーに従うことを確認するには、ポリシーを明確に文書化し、ドキュメントにアクセスできるようにすることが重要です。定期的なコードレビューは、ポリシーの実施にも役立ちます。また、ドキュメント組織のルールに準拠しているかどうかを確認できる自動化ツールの使用を検討してください。

プロジェクトの途中でファイル組織ポリシーを変更できますか？

はい、プロジェクトの途中でファイル組織ポリシーを変更できますが、これはワークフローの混乱を避けるために注意して行う必要があります。変更を加える前に、提案された新しい戦略についてあなたのチームと話し合い、誰もが変更の理由とそれを実装する方法を理解していることを確認してください。また、関連するドキュメントを更新して、新しいポリシーを反映することも重要です。

プロジェクトファイルを整理するときに依存関係を扱う方法は？

プロジェクトファイルを整理する場合、依存関係の処理が課題になる可能性があります。 1つの方法は、すべての依存関係を別のディレクトリに保存することです。これにより、それらを管理して更新しやすくなります。一部のプログラミング言語とパッケージマネージャーは、ほとんどのプロセスを自動化する依存関係を管理するためのツールも提供します。

プロジェクトファイルを整理する際には、どのような一般的な間違いを避けるべきですか？

プロジェクトファイルを整理する際に避けるべき一般的な間違いは、次のことを含みます。ファイル構造を事前に計画せず、一貫した命名規則に従わず、ファイル組織のポリシーを記録せず、ファイル構造の不規則なチェックとリファクタリング。これらのエラーを避けることで、コードベースをきれいに、整理し、ナビゲートしやすくすることができます。

ドキュメント組織のベストプラクティスについて詳しく知る方法は？

ドキュメント組織のベストプラクティスを学ぶために利用できる多くのリソースがあります。オンラインチュートリアル、コーディングブートキャンプ、開発者フォーラムは、貴重な洞察を提供できます。さらに、オープンソースプロジェクトのフォルダー構造を調べると、プロジェクトファイルを効果的に整理する方法の実用的な例を提供できます。

以上がコードベースでファイルを適切に整理する方法と騒乱を避ける方法の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。