15 façons d'écrire un javascript auto-documentaire

Points clés pour écrire le code JavaScript auto-documenté

Cet article explorera comment rédiger un code JavaScript auto-documenté et maintenu à documentation auto-documentée à travers des techniques structurées, des conventions de dénomination et des techniques de syntaxe. Bien que le code auto-documenté puisse réduire le besoin de commentaires, il ne remplace pas complètement les bons commentaires et la documentation complète.

Compétences de base

• Technologie structurée: Déplacez le code dans une fonction, remplacez les expressions conditionnelles par des fonctions et utilisez des fonctions pures pour rendre le code plus clair et plus facile à comprendre.
• Convention de dénomination: Variables, fonctions et classes avec des noms significatifs pour améliorer la lisibilité du code.
• Compétences de syntaxe: Évitez d'utiliser des techniques de syntaxe, utilisez des constantes nommées et rendez le code plus clair.
• Extraire le code avec prudence: Évitez le code trop extrait à la recherche de fonctions courtes, ce qui peut réduire la compréhensibilité du code.

Aperçu technique

Nous divisons le code auto-documenté en trois catégories:

• Structure: Utilisez la structure du code ou du répertoire pour clarifier l'objectif du code.
• lié ​​au nom: Par exemple, la dénomination des fonctions ou des variables.
• Syntaxe liée: Utiliser (ou éviter) les fonctionnalités du langage pour rendre le code plus clair.

Technologie structurée

• Déplacez le code dans la fonction: Déplacez le code existant dans une nouvelle fonction pour rendre ses fonctions plus claires. Par exemple, var width = (value - 0.5) * 16; peut être réécrit comme:

<code class="language-javascript">var width = emToPixels(value);

function emToPixels(ems) {
    return (ems - 0.5) * 16;
}</code>

• Remplacez les expressions conditionnelles par des fonctions: convertir les instructions conditionnelles complexes en fonctions pour améliorer la lisibilité.

• Remplacez les expressions par des variables: décomposer les expressions complexes en plusieurs variables pour améliorer la compréhensibilité.

• Interfaces de classe et de module: Les méthodes et les propriétés publiques d'une classe peuvent être utilisées comme documentation de leur utilisation. Une interface claire peut refléter directement l'utilisation de la classe.

• Groupement de code: Le regroupement des codes liés peut indiquer qu'il existe une association entre les codes et faciliter la maintenance.

• Utiliser des fonctions pures: Les fonctions pures sont plus faciles à comprendre car leur sortie dépend uniquement des paramètres d'entrée et n'a aucun effet secondaire.

• Répertoire et structure de fichiers: Organisez des fichiers et des répertoires en fonction des conventions de dénomination existantes dans le projet pour faciliter la recherche et la compréhension de code.

Compétences de dénomination

• Renommer de la fonction: Utilisez des verbes en voix active et indiquez explicitement la valeur de retour. Évitez d'utiliser des mots vagues tels que «manipuler» ou «gérer».

• Renommer de la variable: Utilisez un nom significatif et spécifiez l'unité (par exemple widthPx). Évitez d'utiliser des abréviations.

• Adhérer aux conventions de dénomination établies: Maintenir un style de dénomination cohérent dans le projet.

• Utilisez des messages d'erreur significatifs: Assurez-vous que les messages d'erreur lancés par le code sont descriptifs et contiennent des informations pertinentes qui ont provoqué l'erreur.

Compétences en grammaire

• Évitez d'utiliser des conseils de grammaire: Évitez d'utiliser des conseils de grammaire difficile à comprendre, tels que imTricky && doMagic();, et utiliser des instructions plus claires if.

• Utiliser les constantes nommées pour éviter les valeurs magiques: utiliser les constantes nommées au lieu de valeurs magiques pour améliorer la lisibilité du code et la maintenabilité.

• Évitez les drapeaux booléens: Les drapeaux booléens peuvent rendre le code difficile à comprendre et doivent être pris en compte pour une approche plus claire.

• Soyez pleinement utilisé des fonctionnalités linguistiques: Utilisez les fonctionnalités fournies par les langues, telles que les méthodes d'itération du tableau, pour rendre le code plus concis et plus facile à comprendre.

anti-mode

• Code surextrait pour les fonctions courtes: Évitez le code surextraitant afin de poursuivre des fonctions courtes, ce qui peut réduire la compréhensibilité du code.

• Ne le forcez pas: Si une méthode ne convient pas, ne le forcez pas à l'utiliser.

Résumé

La rédaction du code auto-documenté peut considérablement améliorer la maintenabilité du code et réduire le besoin de commentaires. Cependant, le code auto-documenté ne peut pas remplacer complètement les documents ou les commentaires. Les bonnes annotations et la documentation API sont encore cruciales pour les grands projets.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!