Skip to content

Latest commit

 

History

History
128 lines (92 loc) · 5.8 KB

naming-conventions.md

File metadata and controls

128 lines (92 loc) · 5.8 KB
Raw

Conventions Générales de Nommage

Ce document rassemble les bonnes pratiques appliquées par l'agence web Alsacreations.fr concernant "les Conventions de nommage". Ces indications sont destinées à évoluer dans le temps et à s'adapter à chaque nouveau projet.

Langue

La langue employée pour tout texte rédigé au cours d’un projet est le français :

  • les commentaires dans un fichier de code,
  • les titres de commit (versionning),
  • les instructions dans le fichier readme.md,
  • toute documentation explicative ou technique.

La langue anglaise demeure préconisée pour :

  • L’architecture et les dossiers du projet (assets, layout, components, fonts)
  • Le nom des fichiers (single-something.html, ProductCard.vue)
  • Les branches principales de versionning (main, develop), avec possibilités en français si besoin (recette)
  • Les composants, classes HTML, etc.

Formatage

La règle d’indentation appliquée par défaut est de 2 espaces pour l’ensemble des langages. Les conventions spécifiques à certains langages ou technologies (PHP avec 4 espaces) sont prioritaires sur cette règle générale au cas par cas.

Par exemple :

  • PHP suit la convention de styles PSR-12 "Extended Coding Style" qui stipule “Code MUST use an indent of 4 spaces for each indent level, and MUST NOT use tabs for indenting.”
  • WordPress suit la convention PSR-5 "PHPDoc Standard"
  • Les Documentations techniques se réfèrent à PHPdoc, JSdoc, etc.

On débute par /** dans VSCode qui auto-complète en optant pour un formatage conventionnel.

JSDoc est supporté nativement par VSCode, mais peut être facilité par une extension JSDoc.

Exemple :

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {}

Toujours configurer et appliquer les Linters et Formatters editorconfig, ESlint et Stylelint (voir détails dans la ressource VSCode)

Union de mots

Les conventions d’usage pour lier les mots sont :

  • under_score :
    • Fonctions PHP
  • kebab-case :
    • fichiers pouvant se retrouver dans les URLs (ex : single-something.html)
    • classes HTML/CSS
  • PascalCase :
    • noms de composants dans Vue/Nuxt (ex : ModalAccountMixins.js)
    • classes PHP
  • camelCase :
    • variables et fonctions dans JavaScript (ex : dateFormat, getResellSwitchQty())
    • méthodes PHP
  • ALL_CAPS (SCREAMING_SNAKE_CASE) :
    • constantes
  • snake_case :
    • nope

Synonymes

Si on privilégie l'anglais pour le code et malgré son apparente simplicité, il existe toujours des synonymes.

Exemple à ne pas reproduire (coexistence de cancel/remove/delete) :

<button class="cancelProduct" onclick="removeProduct(1337)">
  <svg id="remove" ...>
</button>
function removeProduct(id) {
   axios.delete('/api/product', id)
}

Suggestions et raisons :

  • Ajouter à une liste : add ou append
  • Suppression complète de données : delete (car les méthodes REST utilisent DELETE)
  • Retirer un élément d'une liste : remove
  • Annulation d'action : cancel
  • Ouverture/fermeture : open/close (alternativement : toggle)
  • Récupération de données : get (existe en tant que méthode HTTP)
  • Remplacement de données : set (écrase tout)
  • Mise à jour de données : update (similaire à patch, peut remplacer certaines clés d'un objet mais pas toutes)
  • Réinitialisation à l'état initial : reset
  • Callback/gestionnaire : handle (ex : handleClick)
  • Dénombrement : count (ex: pageCount)
  • États : is ou has (ex : isOpened, hasItems)
  • Précédent/suivant : prev/next

🔖 Voir aussi :

Nommage pour code en attente

En phase de développement d'un projet, les notes de modifications et améliorations restant à réaliser dans le code (CSS, HTML, JavaScript) doivent être consignées et notées TODO: (et non @TODO) ou FIXME: selon leur fonction :

  • TODO: Partie de code non finalisée, non mis en oeuvre (par exemple TODO: implémenter les données, <a href="TODO:">)
  • FIXME: Partie de code à améliorer, à modifier pour être plus performant, plus maintenable, etc. (par exemple : FIXME: mieux gérer le responsive, FIXME: refactoring)

L'extension Todo Tree permet de mettre en exergue les tags TODO, FIXME, HACK... ainsi que les lister dans un arbre. On active les couleurs avec le paramètre "todo-tree.highlights.useColourScheme": true.

En fin de phase de développement, avant la livraison du projet, il est fondamental de vérifier la présence indésirable de ces tags au sein du code. L'idéal étant qu'un projet soit livré sans aucun tag TODO:.

Remplissage et données d'exemple

Pour les URLs vers des domaines fictifs, on privilégie https://example.org/ ou https://example.com/ qui sont réservés à cet usage.

Convention pour Langages spécifiques et Frameworks

Les règles de nommage particulières à chaque langage sont consignées dans leurs Guidelines respectives :