Conventions Générales de Nommage

Statut : Working Draft (WD)

Ces présentes conventions ont pour objectif d'harmoniser les noms des fichiers, des fonctions ou classes utilisées au sein des projets web de l'agence Alsacréations.

Convention de Langue

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

Cela concerne :

  • 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)
  • Les branches principales de versionning (master, develop), avec possibilités en français si besoin (recette)

Convention de 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, WordPress) 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 Editorconfig et Prettier (voir détails dans les Guidelines VSCode)

Convention d'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

Convention pour Langages spécifiques et Frameworks

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