So organisieren Sie Dateien in Ihrer Codebasis ordnungsgemäß und vermeiden Sie Chaos

Organisation und Wartung großer Codebasis: Hauptbibliothek, Daten, Benutzeroberfläche, Dokumentation und Wiki, Tests, Legacy-Komponenten und Komponenten von Drittanbietern ... wie kann man die Reihenfolge all dieser Inhalte verfolgen und aufrechterhalten? Die Organisation von Dateien in Codebasen kann eine schwierige Aufgabe sein.

Mach dir keine Sorgen - wir können es schaffen! In diesem Artikel werden die am häufigsten verwendeten Systeme für kleine und große Projekte überprüft und einige leicht zu befolgende Best Practices bereitgestellt.

Schlüsselpunkte

• Das Organisieren von Dateien in Ihrer Codebasis kann Probleme reduzieren und Zeit sparen, wenn Sie in Zukunft auf Inhalte zugreifen und sie überprüfen müssen. Es ist sehr wichtig, grundlegende Regeln für die Namensberechtigung, die Verarbeitung von Projektdokumentationen und die Organisation effektiver Workflows festzulegen.
• Jedes Softwareprojekt sollte eine Readme, ChangeLog, Kopierlizenz und .Gitignore -Datei haben. Abhängig von der Projektsituation können auch andere Dateien wie Autoren, Fehler, Beiträge/Hacking, FAQ, Installation, Nachrichten, Dank, Todo/Roadmap, Version/Release enthalten sein.
• Dateien sollten in Ordner von Komponenten oder Subsystemen organisiert werden, aber Verzeichnisse sollten erstellt werden, um die Dinge verwaltbar zu halten. Bestimmte Arten von Dateien, wie Daten, Binärdateien und Einstellungen, sollten vom Projekt ausgeschlossen werden.
• Der Schlüssel zur Dokumentation der Organisation liegt in Konsistenz. Unabhängig davon, ob es sich um die Benennung von Verzeichnissen oder Dateien oder die Struktur eines Projekts handelt, erleichtert die Aufrechterhaltung der Konsistenz die Codebasis einfacher zu navigieren und zu verstehen.

Warum sich die Mühe machen?

Wie bei fast allen Projekten im Zusammenhang mit dem Projektmanagement-Dokumentation, Software-Einreichung, Bereitstellung-, profitieren Sie stark von einem bewussten, programmatischen Ansatz. Dies verringert nicht nur die aktuellen Probleme, sondern speichert Ihnen und Ihrem Team auch wertvolle Zeit, wenn der Inhalt in Zukunft schnell zugegriffen und überprüft werden muss.

Sie können sich definitiv an den Funktionsnamen von allem erinnern, was Sie gerade schreiben, und finden Sie schnell die Dateien, die Sie bearbeiten müssen, und genau zu sagen, was funktioniert und was nicht - oder was Sie denken. Aber können Sie dasselbe über das Projekt sagen, an dem Sie letztes Jahr gearbeitet haben?

Lassen Sie uns zugeben: Softwareprojekte halten möglicherweise Monate oder sogar Jahre der Inaktivität. Eine einfache ReadMe -Datei kann viele Dinge für Ihre Kollegen oder Ihre Zukunft ausführen. Berücksichtigen wir jedoch andere Möglichkeiten, wie Sie ein Projekt erstellen und einige Grundregeln erstellen können, um Dateien zu benennen, Projektdokumentation zu verarbeiten und in gewissem Maße einen effektiven Workflow zu organisieren, der den Test der Zeit besteht.

Dinge verstehen

Wir werden eine "Grundlinie" für die Dokumente in einem Organisationsprojekt einrichten - eine Logik, die uns in vielen Situationen im Rahmen der Softwareentwicklung dient.

Wie bei unseren Regeln über die korrekte Einreichung von Codebasisänderungen ist keine davon in Stein gemeißelt, und in Bezug auf ihren Wert schlagen Sie und Ihr Team möglicherweise unterschiedliche Leitprinzipien vor. Wie auch immer,

Konsistenz ist der Name des Spiels. Stellen Sie sicher, dass Sie verstehen (und diskutieren oder argumentieren), was die Regeln sind, und befolgen Sie sie, nachdem der Konsens erreicht ist.

Erforderliche Dokumente

Dies ist eine Referenzliste von Dateien, die fast jedes Softwareprojekt haben sollte:

• Readme: Dies ist, was Github für Sie unter dem Quellbaum vorlegt, um den Inhalt des Projekts zu erklären, wie die Dateien organisiert sind und wo weitere Informationen finden können. ChangeLog: Listet in jeder Version oder Überarbeitung neue, modifizierte oder deaktivierte Inhalte auf-normalerweise zur Bequemlichkeit in anti-chronologischer Reihenfolge (die neuesten Änderungen stehen im Vordergrund).
• Kopieren der Lizenz: Eine Datei, die den vollständigen Text der Lizenz enthält, die die Software abdeckt, und gegebenenfalls einige andere Copyright-Informationen (z. B. eine Lizenz von Drittanbietern).
• .gitignore: Angenommen, Sie verwenden Git (die Sie am wahrscheinlichsten verwenden), dies ist auch erforderlich, um festzustellen, welche Dateien nicht mit dem Repository synchronisiert sind. (Weitere Informationen zu .gitignore finden Sie im Leitfaden und der Dokumentation von Sprung Start Git und finden Sie in der nützlichen Sammlung von .Gitignore -Vorlagen für einige Ideen.)
Unterstützer

Abhängig von der Projektsituation möchten Sie auch in Betracht ziehen, einige andere Dokumente einzubeziehen:

Autoren: Die Zuordnung der Person, die beim Schreiben des Codes beteiligt ist.

• Fehler: Bekannte Probleme und Anweisungen zur Berichterstattung über neu gefundene Fehler.
• Beitrag/Hacking: Ein Leitfaden für potenzielle Mitwirkende, insbesondere für Open -Source -Projekte.
• FAQ: Sie wissen bereits, was das ist. ;)
• Installation: Anweisungen zum Kompilieren oder Installieren von Software auf verschiedenen Systemen.
• Nachrichten: Ähnlich wie bei Changelog -Dateien, aber für Endbenutzer, nicht für Entwickler.
• Danke: Danke.
• Todo/Roadmap: Eine Liste der geplanten Funktionen.
• Version/Release: Eine Codezeile, die den aktuellen Versionsnummer oder den aktuellen Namen beschreibt.
Ordner von Komponenten oder Subsystemen

wir begegnen oft auf eine Reihe von Funktionen, die zu einem einzigen Konzept kombiniert werden können.

Einige Beispiele könnten:

sein

Internationalisierung (I18N) und Lokalisierung (L18N)

• Authentifizierungsmodul
• add-Ons
Drittanbieter
• Allgemeine Werkzeuge und Cron -Zuweisungen
• Benutzeroberfläche (UI) und Grafik Benutzeroberfläche (GUI)
All dies kann in ein einzelnes "Komponenten" oder "Subsystem" -Verzeichnis organisiert werden - aber sei nicht verrückt!

Wir möchten die Erstellung von Verzeichnissen einschränken, um die Dinge überschaubar zu halten, sei es im Stammverzeichnis (die Hauptkomponenten finden hier) oder rekursiv (in jedem Verzeichnis). Andernfalls verbringen wir möglicherweise viel Zeit damit, routinemäßig Dateien in gut organisierten Verzeichnissen zu durchsuchen.

Bitte schließen Sie diese

aus dem Quellbaum

aus Während wir möchten, dass das Projekt ordentlich und ordentlich ist, gibt es einige Dokumente, die vollständig aus dem Projekt ausgeschlossen werden sollen.

Daten. Möglicherweise sind Sie versucht, ein Daten/ein Verzeichnis im Quellbaum für CSV -Dateien usw. zu haben, insbesondere wenn sie nur ein paar Kilobyten einnehmen. Aber was ist, wenn sie Megabyte oder sogar Gigabyte aufnehmen (was heutzutage nicht ungewöhnlich ist)? Möchten Sie diese wirklich in Ihren Code einreichen, wie Sie es mit Ihrer Codebasis tun würden? NEIN.

Binärdatei. Sie möchten nicht, dass sich das Video -Rendering oder die kompilierten Ausführungsfähigkeiten neben dem Quellcode befinden. Dies sind keine Entwicklungsdateien, sie gehören überhaupt nicht hierher. Wie Datendateien nutzen sie möglicherweise viel Platz.

Einstellungen. Dies ist ein weiteres großes Tabu. Sie sollten keine Anmeldeinformationen, Passwörter oder sogar Sicherheitstoken in Ihre Codebasis platzieren. Wir können hier keine Lösung für dieses Problem abdecken, aber wenn Sie ein Python -Entwickler sind, sollten Sie Python Decouple verwenden.

Fall 1: Webanwendung

Betrachten wir eine Webanwendung - eine Software, die auf einem Webserver ausgeführt wird, auf den Sie über einen Browser zugreifen können, sei es auf einem Desktop oder einem mobilen Gerät. Und unter der Annahme, dass es sich um eine Webanwendung handelt, die eine Mitgliedschaft für den Zugriff auf einen Premium -Service bietet - wahrscheinlich exklusive Berichte, Reise -Tipps oder Videobibliotheken.

Dateistruktur

<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>

Analyse

Dies ist eine grundlegende Webanwendungsstruktur mit Unterstützung für zwei Sprachen (Englisch und vereinfachtes Chinesisch (Gebietsschema -Verzeichnis). Es gibt auch zwei Hauptkomponenten, Abrechnung und Mitglieder.

Wenn Sie mit der Website der Website etwas besser vertraut sind, sieht der Inhalt der Ordner der statischen und der Vorlagen bekannt vor. Möglicherweise ist das einzige ungewöhnliche Element .ElasticBeanStalk, das Bereitstellungsdateien für Amazon Web Services (AWS) und .EnV speichert, in dem nur Einstellungen für Projekte vor Ort wie Datenbankanmeldeinformationen gespeichert sind. Der Rest, wie Readme und Todo, haben wir darüber diskutiert. Tools -Verzeichnis ist ein interessantes Verzeichnis. Hier können wir Skripte speichern, z. B. die Datenbank abschneiden, den Zahlungsstatus überprüfen oder statische Dateien auf dem Cache rendern - im Grunde genommen alles, was nicht die Anwendung selbst ist, sondern dazu beiträgt, dass sie funktioniert.

In Bezug auf die Benennung, wenn wir das Bilderverzeichnis als Bilder/ oder IMG/ oder das Stylesverzeichnis als Styles/ oder CSS/ benennen oder das JavaScript/ Verzeichnis als JS/ benennen, gibt es keinen Unterschied. Die Hauptsache ist, dass die Struktur logisch ist, und wir folgen immer einer bestimmten Konvention, ob es sich um einen langen oder einen kurzen Namen oder einen kurzen Namen handelt.

Fall 2: Desktop -Anwendung

Betrachten wir nun eine Anwendung, die Sie auf Ihrem Computer herunterladen und installieren können. Nehmen wir an, für die Anwendung sind einige Eingaben wie eine CSV -Datei erforderlich und machen dann eine Reihe von Berichten.

In diesem Beispiel werden wir den Quellbaum etwas größer machen.

Dateistruktur

Analyse

<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>

UI/Ordner sind im Wesentlichen der Kern der Anwendung. Der Name des Unterordners ist fast selbstverständlich (eine weitere gute Angewohnheit). Im Gegensatz zu unserem Beispiel für Webanwendungen haben wir hier den Abkürzungsnamen (z. B. JS anstelle von JavaScript) gewählt. Auch hier ist es wirklich wichtig, dass wir über das Projekt konsequent sind.

Früher habe ich vorgeschlagen, die Datendateien aus dem Quellbaum auszuschließen, aber dort gibt es einen Daten/Ordner. Wie könnte das passieren? Stellen Sie sich diesen Baum als Entwicklerbox vor, für die Daten die Anwendung ordnungsgemäß testen müssen. Die Daten sind jedoch immer noch nicht aus der Repository -Synchronisation herausgefolgt, nachdem die in der Datei .gitignore festgelegten Regeln festgelegt sind.

Legacy/ Ordner wird für einen Teil der Anwendung verwendet, die eingestellt werden soll, bietet jedoch einige Funktionen, die möglicherweise nützlich sein können, bis sie vollständig in ein neues System überarbeitet werden. Daher bietet es eine gute Möglichkeit, den alten Code vom aktuellen Code zu trennen.

Ein Neuzugang hier sind Tests/, an dem die Qualität mithilfe von Unit -Tests und Drittanparty/ein Ort für die Speicherung externer Bibliotheken, die von der Software gefordert werden, sicherstellen können.

Beachten Sie, dass es Doc/ und Wiki/ Ordner gibt, die wie ein Duplikat aussehen können. Es ist jedoch auch durchaus möglich, einen Dokumentordner für den Endbenutzer und ein Wiki für das Entwicklungsteam zu haben - sogar vernünftig.

Zusammenfassung

Die guten Nachrichten, die es wert ist, wiederholt zu werden, ist: Selbst wenn Sie alleine arbeiten, müssen Sie organisiert sein. Hoffentlich bietet Ihnen dieser Artikel einige Ideen, die Sie sofort auf Ihren Workflow bewerben können, um Verwirrung zu verhindern, wenn die Anzahl der Dateien in Ihrer Anwendung zunimmt.

Wie bereits erwähnt, können sich die Richtlinien von Zeit zu Zeit ändern, da (fast) jedes Projekt anders ist, ebenso das Team. Im Idealfall entscheiden Sie oder Ihr Team, wie Sie ein Projekt erstellen. Fügen Sie ein kleines Dokument hinzu, um die Gründe für diese Struktur zu beschreiben - und Sie bleiben von nun an diese Regeln.

Denken Sie daran, dass es für viele der Richtlinien hier keine Rolle spielt, ob Sie einen Armaturenbrett oder einen Unterstrich auswählen, um eine Datei zu benennen (wählen Sie eines der vielen Themen). Der Schlüssel ist Konsistenz.

Weiteres Lesen

• Die Projektstruktur aus dem "Python Erste Start Guide".
• Systemmethode zur Verwaltung der Projektordnerstruktur von UX Collective.
• effektives Projektmanagement: traditionell, agil, extrem, hybrid

FAQs über das Organisieren von Projektdokumenten (FAQ)

Was sind die Vorteile der Organisation von Projektdokumenten strukturiert?

Es gibt viele Vorteile der Organisation von Projektdokumenten auf strukturierte Weise. Erstens verbessert es die Lesbarkeit und Wartbarkeit des Codes. Wenn Dateien logisch organisiert sind, ist es für Entwickler einfacher, die Codebasis zu verstehen und Änderungen vorzunehmen, ohne vorhandene Funktionen zu brechen. Zweitens verbessert es die Teamarbeit. Wenn mehrere Entwickler an demselben Projekt arbeiten, stellt eine gut organisierte Dateistruktur sicher, dass jeder weiß, wo er ein bestimmtes Snippet finden kann. Schließlich beschleunigt es den Entwicklungsprozess. Entwickler verbringen weniger Zeit damit, Dateien zu durchsuchen und mehr Zeit zu schreiben und Code zu optimieren.

Wie kann man die optimale Struktur von Projektdateien bestimmen?

Die optimale Struktur einer Projektdatei hängt von der Art und Komplexität des Projekts ab. Für kleine Projekte kann eine einfache Verzeichnisstruktur ausreichen. Für größere Projekte mit mehreren Komponenten benötigen Sie jedoch möglicherweise eine komplexere Struktur. Betrachten Sie Faktoren wie die von Ihnen verwendete Programmiersprache, den von Ihnen verwendeten Framework oder die Bibliothek sowie die Vorlieben des Teams. Es ist wichtig, die Struktur flexibel zu machen, damit sich das Projekt wächst.

Was sind einige gängige Strategien für die Organisation von Code?

Es gibt mehrere Strategien für die Organisation von Code. Eine gemeinsame Methode besteht darin, Dateien nach Funktion zu gruppieren. Dies bedeutet, dass alle Dateien, die sich auf eine bestimmte Funktion beziehen, im selben Verzeichnis gespeichert werden. Eine andere Möglichkeit besteht darin, Dateien nach Typ zu gruppieren, z. B. CSS, JavaScript und HTML -Dateien in verschiedene Verzeichnisse aufzuteilen. Einige Entwickler bevorzugen es, einen hybriden Ansatz zu verwenden, der Elemente beider Strategien kombiniert. Der Schlüssel ist, eine Strategie zu wählen, die für Ihr Projekt und Ihr Team sinnvoll ist.

Wie kann ihre Organisation mit wachsender Codebasis aufrechterhalten werden?

Wenn die Codebasis wächst, ist es wichtig, die Dateistruktur regelmäßig zu überprüfen und neu zu überprüfen. Dies kann das Aufteilen großer Dateien in kleinere, überschaubarere Dateien oder die Umstrukturierung von Verzeichnissen umfassen, um den aktuellen Stand des Projekts besser widerzuspiegeln. Automatisierungstools können dazu beitragen, Bereiche in der Codebasis zu identifizieren, die ungeschickt oder schwer zu warten sind. Regelmäßige Codeüberprüfungen können auch dazu beitragen, dass der neue Code der festgelegten Dateistruktur entspricht.

Welche Rolle spielt die Namenskonventionen in der Dateiorganisation?

Namenskonventionen spielen eine entscheidende Rolle in der Dokumentorganisation. Konsistente, beschreibende Dateinamen erleichtern das Verständnis, was jede Datei auf einen Blick enthält. Dies kann den Entwicklungsprozess erheblich beschleunigen, insbesondere wenn es um große Projekte geht oder mit Teams zusammenarbeitet. Die Benennung von Konventionen sollte zu Beginn des Projekts vereinbart werden und bleibt immer konsequent.

Wie können Sie sicherstellen, dass alle Teammitglieder meiner Dateiorganisationsstrategie folgen?

Um sicherzustellen, dass alle Teammitglieder Ihrer Dateiorganisationsrichtlinie folgen, ist es wichtig, Ihre Richtlinien klar zu dokumentieren und das Dokument zugänglich zu machen. Regelmäßige Code -Überprüfungen können auch dazu beitragen, die Richtlinien durchzusetzen. Erwägen Sie außerdem ein Automatisierungswerkzeug, mit dem Sie überprüfen können, ob es Ihren Regeln für die Organisation der Dokumente entspricht.

Kann ich meine Dateiorganisationsrichtlinie in der Mitte des Projekts ändern?

Ja, Sie können die Richtlinien für die Dateiorganisation in der Mitte des Projekts ändern. Dies sollte jedoch mit Vorsicht erfolgen, um zu vermeiden, dass der Workflow stört. Bevor Sie Änderungen vornehmen, besprechen Sie die vorgeschlagene neue Strategie mit Ihrem Team und stellen Sie sicher, dass jeder die Gründe für die Veränderung versteht und wie sie implementiert werden können. Es ist wichtig, auch alle relevanten Dokumente zu aktualisieren, um die neue Richtlinie widerzuspiegeln.

Wie geht es mit Abhängigkeiten beim Organisieren von Projektdateien um?

Bei der Organisation von Projektdateien kann die Behandlung von Abhängigkeiten eine Herausforderung sein. Eine Möglichkeit besteht darin, alle Abhängigkeiten in einem separaten Verzeichnis zu speichern. Dies erleichtert es, sie zu verwalten und zu aktualisieren. Einige Programmiersprachen und Paketmanager bieten auch Tools zum Verwalten von Abhängigkeiten, die den größten Teil des Prozesses automatisieren.

Welche häufigen Fehler sollten bei der Organisation von Projektdateien vermieden werden?

Einige häufige Fehler, die bei der Organisation von Projektdateien vermieden werden sollten, umfassen: Nicht planen die Dateistruktur im Voraus, keine konsistenten Benennungskonventionen, keine Richtlinien für die Organisation von Dateien sowie unregelmäßige Überprüfung und Wiederbelebung von Dateistrukturen. Das Vermeiden dieser Fehler kann dazu beitragen, die Codebasis ordentlich, organisiert und leicht zu navigieren zu halten.

Erfahren Sie mehr über Best Practices in der Dokumentorganisation?

Es stehen viele Ressourcen zur Verfügung, um Best Practices für die Dokumentorganisation zu erlernen. Online -Tutorials, Coding -Bootcamps und Entwicklerforen können wertvolle Erkenntnisse liefern. Die Untersuchung der Ordnerstruktur eines Open -Source -Projekts kann außerdem praktische Beispiele für die effektive Organisation von Projektdateien liefern.

Das obige ist der detaillierte Inhalt vonSo organisieren Sie Dateien in Ihrer Codebasis ordnungsgemäß und vermeiden Sie Chaos. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!