Bonnes pratiques pour la documentation

Garder les lignes sous les 80 caractères

Pour faciliter la lecture de votre code, gardez les lignes sous les 80 caractères. Cela facilite la lecture rapide et le débogage.

À évjter :

<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.12.0/css/all.css" integrity="sha384-REHJTs1r2ErKBuJB0fCK99gCYsVjwxHrSU0N7I1zl9vZbggVJXRMsv/sLlOAGb4M" crossorigin="anonymous"p>

Mieux :

<link 
  rel="stylesheet" 
  href="https://use.fontawesome.com/releases/v5.12.0/css/all.css" 
  integrity="sha384-REHJTs1r2ErKBuJB0fCK99gCYsVjwxHrSU0N7I1zl9vZbggVJXRMsv/sLlOAGb4M" 
  crossorigin="anonymous">

Utilisez des commentaires

Ajoutez des commentaires à votre code pour expliquer pourquoi vous avez pris certaines décisions. Cela réduit les chances que vos futurs collègues brisent les fruits de votre travail.

Niveau 0 : Pas de commentaires

section.classList.add('dpd-section');
if (sectionData['sectionOrder'] != 0) section.classList.add('dpd-hidden');

section.dataset.order = sectionData['sectionOrder'];
section.dataset.name = sectionData['sectionID'];

if (sectionData['sectionTitle']) {
  header.innerText = sectionData['sectionTitle'];
  header.className = 'dpd-section-header';
  section.appendChild(header);
}

Niveau 1 : Traduire le code en anglais ou en français

// Ajouter les classes section et hidden
section.classList.add('dpd-section');
if (sectionData['sectionOrder'] != 0) section.classList.add('dpd-hidden');

// Ajouter les attributs de l'ensemble de données
section.dataset.order = sectionData['sectionOrder'];
section.dataset.name = sectionData['sectionID'];

// Mettre à jour les attributs d'en-tête et le parent
if (sectionData['sectionTitle']) {
  header.innerText = sectionData['sectionTitle'];
  header.className = 'dpd-section-header';
  section.appendChild(header);
}

Niveau 2 : Expliquer ce que vous avez fait

// Mettre en forme la section
section.classList.add('dpd-section');
if (sectionData['sectionOrder'] != 0) section.classList.add('dpd-hidden');

// Ajouter les métadonnées de la section
section.dataset.order = sectionData['sectionOrder'];
section.dataset.name = sectionData['sectionID'];

// Ajouter un en-tête à la section
if (sectionData['sectionTitle']) {
  header.innerText = sectionData['sectionTitle'];
  header.className = 'dpd-section-header';
  section.appendChild(header);
}

Niveau 3 : Expliquer pourquoi vous avez fait ce que vous avez fait

// dpd-section ajoute un style de base
// dpd-hidden masque les sections qui ne sont pas les premières dans l'ordre
section.classList.add('dpd-section');
if (sectionData['sectionOrder'] != 0) section.classList.add('dpd-hidden');

// Ajouter des attributs utiles pour sélectionner la section ultérieurement
section.dataset.order = sectionData['sectionOrder'];
section.dataset.name = sectionData['sectionID'];

// Si un en-tête facultatif est spécifié, ajouter une étiquette
if (sectionData['sectionTitle']) {
  header.innerText = sectionData['sectionTitle'];
  header.className = 'dpd-section-header';
  section.appendChild(header);
}

Ajouter des docstrings pour les fonctions/méthodes

Pour chaque fonction ou méthode de classe que vous créez, ajoutez un docstring qui résume l'objectif de la fonction, les paramètres d'entrée et les valeurs de sortie.

updateVisibleOptions(id, options) {
  /*
  Met à jour la visibilité des options spécifiées en utilisant 
  une requête de liste déroulante.

  Paramètres
    ---------------
  id (type : string)
  - Identifie la requête de liste déroulante à utiliser pour le filtrage.
  options (type : array)
  - Tableau d'éléments DOM dont il faut mettre à jour la visibilité.
  */
  
  if (this.#queries[id] === undefined) this.#queries[id] = "";
  
  let visible = filterOptions(options, this.#queries[id]);
  
  // Mettre à jour l'affichage des éléments
  for (let o of options) {
    if (visible.includes(o)) o.classList.remove('dpd-invisible');
    else if (!o.classList.contains('dpd-option-select-all'))
      o.classList.add('dpd-invisible');
  }
}

Divisez votre code en sections

Diviser votre code en sections le rend plus facile à lire et à maintenir.

• Vous pouvez diviser un fichier main.js en un fichier data.js pour le traitement des données, un fichier listeners.js pour les entrées utilisateur et un fichier graph.js pour générer des graphiques.
• Cet exemple CodePen (en anglais seulement) montre comment créer de petites sous-fonctions.
• Vous pouvez utiliser des sous-conditions

set sections(list) {
  // sous-condition un
  const validArr = Array.isArray(list);
  
  // sous-condition deux
  let hasObjs = true;
  for (let el of list) {
    hasObjs = hasObjs && (typeof el === 'object');
  }   
  
  // condition principale
  if (validArr && hasObjs) this.#sections = list;
  else
    console.error('list doit être un tableau avec 1+ objet(s) comme élément(s)');
  }
}

De plus, organiser les fichiers en sous-sections avec des en-têtes clairs peut aider les lecteurs à naviguer facilement dans votre code :

Date de modification :

2023-04-12