Ce bloc-notes mdBook vous est proposé avec passion par Marc JESTIN — Happy Numeric.
À votre service pour vous accompagner dans vos projets numériques.
Contact : https://happynumeric.fr/me-contacter.
Conventions de nommage
Lorsque nous nous lançons dans la création d'un projet mdBook, il est préférable d'appliquer des conventions afin d'augmenter notre productivité et d'améliorer la lisibilité de nos supports.
Il existe plusieurs conventions qui sont importantes au premier rang desquelles :
- les conventions de nommage ;
- les conventions de codage ;
- les conventions d'écriture.
Conventions de nommage
Les conventions de nommage concernent les différents objets qui sont manipulés en développement.
Dans le cadre d'un projet mdBook, cela se résume à convenir de règles pour donner des noms à :
- des dossiers :
- le dossier du projet mdBook lui-même ;
- les différents sous-dossiers du dossier
Nom-du-projet/src
(par défaut) ;
- des fichiers :
fichiers.md
;- images ;
- codes-sources.rs ;
- etc.
Ces conventions de nommage peuvent préciser les règles qui s'appliquent pour le classement d'un certain nombre de fichiers et de dossiers, le nom complet étant par exemple :
Nom-du-projet/NomDeLaRubriqueDuSommaireMdbook/nom-de-la-page-mdbook.md
Bien entendu, ces conventions de nommage prennent en considération les règles de fonctionnement de mdBook.
Pour ma part, j'ai choisi :
- règles applicable à tous
- tous les mots sont reliés par un
-
; - les caractères français sont acceptés, par exemple le
é
ou leç
.
- tous les mots sont reliés par un
- pour le dossier du projet mdBook :
- lettres capitales ou majuscules autorisées ;
- respect de la majuscule au nom propre Rust ;
- respect de la convention d'écriture pour mdBook.
- pour tous les autres dossiers et fichiers :
- lettres minuscules, quel que soit le contexte.
- début du nom des
fichiers.md
: ils commencent toujours parmdbook
(en minuscules, par application de la règle associée), tout comme leur titre. - début du nom des
fichiers.md
des chapitres du sommaire mdBook non numérotés du début du sommaire mdBook :mdbook-bloc-notes
.
Petite anecdote au sujet des conventions de nommage
J'ai choisi d'utiliser des caractères accentués.
C'est un choix qui pouvait coûter cher et qui peut encore coûter cher en développement et la plupart des développeurs savent qu'il vaut mieux ne pas sortir des codes ASCII de base.
Dans ma jeunesse, j'ai un jour travaillé à développer un code informatique dans un environnement bureautique. Le développement en lui-même n'était pas complexen mais des suites d'un choix de nommage d'un des dossiers, le comportent de mon code semblait TOTALEMENT ALÉATOIRE !!!
Cela m'a fait perdre beaucoup de temps et m'a causé beaucoup de tracas inutiles.
En conclusions :
- ne sous-estimez pas l'impact de ce qui peut ressembler de loin à des détails tatillons ;
- ici l'enjeu est faible, et l'intérêt est grand (référencement naturel et lisibilité). Je ne ferais pas ce choix s'il s'agissait d'un développement de code informatique.
Ce bloc-notes mdBook vous est proposé par Marc JESTIN — Happy Numeric. |
Formation, rédaction de documentations techniques ou organisationnelles, mise en place de solutions documentaires internes et externes, assistance à maîtrise d'ouvrage, etc. |
Contact : https://happynumeric.fr/me-contacter |
N'hésitez pas à me faire votre feedback, me signaler des erreurs ou des compléments que vous souhaiteriez que j'ajoute à ce bloc-notes mdBook.
Cliquez ici pour me contacter
À propos de cette page
Création : 14 mars 2023
Dernière mise à jour : 21 mars 2023 22:33