Comment organiser correctement les fichiers dans votre base de code et éviter le chaos –

La bibliothèque principale, les données, l'interface utilisateur, les documents et le wiki, les tests, les composants hérités et tiers… Comment pouvons-nous suivre et maintenir l'ordre dans tout cela? L'organisation des fichiers dans votre base de code peut devenir un défi de taille

Détendez-vous – nous avons cela! Dans cet article, nous passerons en revue les systèmes les plus courants pour les petits et les grands projets, avec quelques bonnes pratiques faciles à suivre.

Pourquoi s'embêter?

Comme avec à peu près toutes les tâches liées à gestion de projet – documentation, validations de logiciels, déploiement – vous bénéficierez d'une approche programmatique consciente. Non seulement cela réduira les problèmes maintenant, mais cela vous fera également gagner du temps de qualité à vous et à votre équipe à l'avenir lorsque vous aurez besoin d'accéder rapidement à des choses et de les consulter.

Vous pouvez sûrement rappeler les noms de fonctions depuis le haut de votre tête pour tout ce que vous codez en ce moment, et trouvez rapidement un fichier que vous devez modifier, et dites clairement ce qui fonctionne à partir de ce qui ne fonctionne pas – ou du moins vous le pensez. Mais pourriez-vous en dire autant de ce projet sur lequel vous travailliez l'année dernière?

Admettons-le: les projets logiciels peuvent durer des mois et même des années . Un simple fichier README pourrait faire beaucoup pour vos collègues ou votre futur moi-même. Mais réfléchissons aux autres façons de structurer votre projet et établissons des règles de base pour nommer les fichiers, traiter la documentation du projet et, dans une certaine mesure, organiser un flux de travail efficace qui résisterait à l'épreuve du temps.

Making Sense of Things [19659004] Nous établirons une «base de référence» pour organiser les fichiers dans un projet – une logique qui nous servira pour un certain nombre de situations dans le cadre du développement de logiciels.

Comme pour nos règles pour commettre des modifications à votre codebase de la bonne façon rien de tout cela n'est gravé dans la pierre, et pour ce que ça vaut, vous et votre équipe pourriez trouver des directives différentes. Dans tous les cas, la cohérence est le nom du jeu . Assurez-vous de comprendre (et de discuter ou de contester) les règles et de les suivre une fois que vous êtes parvenu à un consensus.

L'ensemble obligatoire

Il s'agit d'une liste de référence de fichiers que presque tous les projets logiciels devraient avoir:

• LISEZ-MOI : voici ce que GitHub vous rend juste sous le sourcetree, et cela peut aller un long chemin pour expliquer en quoi consiste le projet, comment les fichiers sont organisés et où trouver plus d'informations.
• CHANGELOG : pour lister les nouveautés, les modifications ou les abandons sur chaque version ou révision – normalement dans un ordre chronologique inverse pour plus de commodité (dernières modifications en premier).
• COPYING LICENSE : un fichier contenant le texte intégral de la licence couvrant le logiciel, y compris des informations supplémentaires sur les droits d'auteur, si nécessaire (telles que des licences tierces).
• .gitignore : en supposant que vous utilisez Git (vous le plus probablement), ce sera également un incontournable t les fichiers à ne pas synchroniser avec le référentiel. (Voir Introduction de Jump Start Git sur .gitignore et la documentation pour plus d'informations, et jetez un œil à une collection de modèles .gitignore utiles pour quelques idées. )

Acteurs de soutien

Certains fichiers supplémentaires que vous pourriez également envisager d'inclure, selon le projet:

• AUTEURS : crédits à ceux qui ont participé à l'écriture du code.
• BOGUES : problèmes connus et des instructions pour signaler les bogues récemment détectés.
• CONTRIBUTION / HACKING : guide pour les contributeurs potentiels, particulièrement utile pour les projets open-source.
• FAQ : vous savez déjà ce que cela est. 😉
• INSTALL : instructions sur la façon de compiler ou d'installer le logiciel sur différents systèmes.
• NOUVELLES : similaire au fichier CHANGELOG mais destiné aux utilisateurs finaux, non
• MERCI : remerciements.
• TODO / FEUILLE DE ROUTE : une liste des fonctionnalités à venir.
• VERSION / VERSION : une ligne décrivant le numéro de version ou le nom de la version actuelle.

Dossiers pour composants ou sous-systèmes

Souvent, nous rencontrons un ensemble de fonctionnalités qui peuvent être regroupées en un seul concept.

Quelques exemples pourraient be:

• internationalisation (i18n) et localisation (l18n)
• modules d'authentification
• modules complémentaires tiers
• outils à usage général et tâches cron
• interface utilisateur (UI) et interface utilisateur graphique ( GUI)

Tout cela peut être organisé en un seul répertoire "composant" ou "sous-système" – mais ne devenez pas fou!

Nous voulons limiter la création de répertoires pour garder les choses gérables à la fois sur le répertoire racine (où les composants principaux seront situés) et récursivement (à l'intérieur de chaque répertoire) . Sinon, nous pourrions finir par passer beaucoup de temps à parcourir régulièrement des fichiers dans des répertoires soigneusement – et excessivement organisés.

Laissez cela Sortir du Sourcetree, s'il vous plaît

Autant que nous voulons le projet pour être soigné et organisé, il y a certains types de fichiers que nous voulons laisser entièrement en dehors.

Données . Vous pourriez être tenté d'avoir un répertoire data / dans votre sourcetree pour les fichiers CSV et autres, surtout s'ils ne prennent que quelques kilo-octets. Mais qu'en est-il s'ils prennent des mégaoctets ou même des gigaoctets (ce qui n'est pas inhabituel de nos jours)? Voulez-vous vraiment enregistrer ce dans votre base de code comme s'il s'agissait de code? No.

Fichiers binaires . Vous ne voulez pas de rendus de vidéos ou de fichiers exécutables compilés à côté du code source. Ce ne sont pas des fichiers de développement, et ils n'appartiennent tout simplement pas ici. Comme pour les fichiers de données, ils peuvent également finir par utiliser beaucoup d'espace.

Paramètres . Ceci est un autre grand NON. Vous ne devez pas mettre d'informations d'identification, de mots de passe ou même de jetons de sécurité dans votre base de code. Nous ne pouvons pas vous expliquer comment contourner ce problème ici, mais si vous êtes un développeur Python, envisagez d'utiliser Découple Python .

Cas 1: Application Web

Considérons une application Web – logiciel qui s'exécute sur un serveur Web et auquel vous pouvez accéder via le navigateur, sur votre ordinateur de bureau ou votre appareil mobile. Et disons qu'il s'agit d'une application Web qui offre un abonnement pour accéder à un service premium de toutes sortes – peut-être des rapports exclusifs, des conseils de voyage ou une bibliothèque de vidéos.

Structure des fichiers

 ├── .elasticbeanstalk
├── .env
├── facturation
├── changelog.txt
├── locale
│ ├── fr
│ └── zh_Hans
├── membres
├── readme.txt
├── statique
│ ├── polices
│ ├── images
│ ├── javascript
│ └── styles
├── modèles
│ ├── admin
│ └── frontend
├── todo.txt
└── outils

Analyse

Il s'agit d'une structure de base pour une application Web prenant en charge deux langues – anglais et chinois simplifié pour la Chine continentale (répertoire locale ). Également deux composants principaux, facturation et membres .

Si vous êtes un peu familier avec le développement de sites Web, le contenu de la statique Les dossiers et modèles peuvent vous sembler familiers. Les seuls éléments inhabituels pourraient peut-être être .elasticbeanstalk qui stocke les fichiers de déploiement pour Amazon Web Services (AWS), et .env qui localement seulement stocke les paramètres pour le projet, telles que les informations d'identification de la base de données. Le reste, comme README et TODO nous en avons déjà discuté.

Le répertoire tools est intéressant. Ici, nous pouvons stocker des scripts qui, par exemple, élaguent la base de données, ou vérifient le statut d'un paiement, ou rendent des fichiers statiques dans un cache – essentiellement, tout ce qui n'est pas l'application elle-même mais qui aide à la faire fonctionner correctement. [19659002] En ce qui concerne la dénomination, cela ne fait pas beaucoup de différence si nous nommons le répertoire images images / ou img / ou le répertoire styles styles / ou css / ou le répertoire javascript / js / . L'essentiel est que la structuration soit logique, et nous suivons toujours quelque chose d'une convention, soit des noms descriptifs longs, soit des noms courts.

Cas 2: Desktop App

Considérons maintenant une application que vous pouvez télécharger et installer sur ton ordinateur. Et disons que l'application prend des entrées, telles que des fichiers CSV, et présente une série de rapports par la suite.

Dans ces exemples, nous allons laisser l'arbre source grossir un peu plus.

Structure de fichier

 ├─ ─ .gitignore
├── données
├── doc
├── héritage
│ ├── tableau de bord
│ ├── img
Système │ └──
├── LICENCE
├── README
├── tests
├── tiers
├── outils
│ ├── intégration_données
│ └── data_scraping
├── ui
│ ├── graphiques
│ ├── css
│ ├── csv
│ ├── tableau de bord
│ ├── img
│ │ └── icônes
│ ├── js
│ ├── rapports
│ └── résumés
├── VERSION
└── wiki

Analyse

Le dossier ui / est essentiellement le cœur de l'application. Le nom des sous-dossiers est à peu près auto-descriptif (une autre bonne pratique). Et contrairement à notre exemple d'application Web, nous avons choisi ici des noms raccourcis (tels que js au lieu de javascript ). Encore une fois, ce qui importe vraiment, c'est que nous soyons cohérents dans le projet.

Plus tôt, j'ai suggéré de laisser les fichiers de données hors de l'arborescence, et pourtant il y a un dossier data / là-dedans. Comment venir? Considérez cet arbre comme la boîte d'un développeur qui a besoin de données pour tester correctement l'application. Mais ces données sont toujours hors de la synchronisation du référentiel, conformément aux règles définies dans le fichier .gitignore .

Le dossier legacy / concerne une partie de l'application qui est interrompue. mais fournit toujours certaines fonctionnalités qui pourraient être utiles jusqu'à ce qu'il soit entièrement refactorisé dans le nouveau système. Il s'agit donc d'un bon moyen de séparer l'ancien code du code actuel.

Autre nouveauté: tests / qui permet de faire de l'assurance qualité avec des tests unitaires, et tiers / , un endroit pour stocker les bibliothèques externes dont le logiciel a besoin.

Notez qu'il existe des dossiers doc / et wiki / qui peuvent ressembler à une duplication. Cependant, il est également parfaitement possible – et même raisonnable – d'avoir un dossier de documentation destiné à l'utilisateur final et un wiki pour l'équipe de développement.

Conclusion

Un bon message mérite d'être répété: be organisé, même en travaillant individuellement . J'espère que cet article vous a donné quelques idées que vous pouvez commencer à implémenter immédiatement dans votre flux de travail pour éviter les dégâts à mesure que le nombre de fichiers dans votre application augmente.

Comme mentionné, les directives peuvent changer ici et là, comme (presque) chaque projet est différent, tout comme les équipes. Idéalement, vous ou votre équipe pourrez décider de la façon dont vous structurez le projet – en ajoutant un petit document décrivant le raisonnement de cette structure – et vous resterez alors cohérent avec ces règles à partir de maintenant.

Et rappelez-vous, avec la plupart des des directives ici, ce n'est pas si important si vous choisissez des tirets ou des traits de soulignement pour nommer les fichiers (pour choisir un sujet parmi plusieurs). La cohérence est la clé .

Pour en savoir plus

Lucero est un programmeur et un entrepreneur qui a le sens du Python, de la science des données et du DevOps. Élevé à Buenos Aires, en Argentine, c'est un musicien qui aime les langues (celles que vous utilisez pour parler aux gens) et la danse.