L'utilisation de Javascript, sont ces bons commentaires ou sont-ils exagérés?

Question

Je souhaite ajouter des commentaires utiles sans être trop bavard. Avant de répondre, imaginez que les fonctions JavaScript soient enterrées quelque part à l'intérieur de centaines ou de milliers de lignes de code source. Notez également que dans les commentaires j'ai donné un peu plus de sens aux paramètres de la fonction en décrivant mieux leur utilisation au lieu d'utiliser les noms réels des paramètres. Je fais cela pour mieux guider l'utilisateur (programmeur) qui pourra ultérieurement refactoriser ou modifier le script.

var ctx = getCanvas();// getCanvas(width, height) 
    grid(ctx);// grid(context, element size, line width, line color) 

    function getCanvas(width = 200, height = 150) { 
     // code to run 
    } 

    function grid(ctx, elSize = 10, width = .3, color = 'green') { 
     // code to run 
    } 

Answer 1

Eh bien, Its always good to have your code properly commented.

Ajouter un commentaire standard/descriptif avant le début de la fonction au lieu de lignes de commentaires.

Il existe plusieurs façons d'ajouter des commentaires en javascript; Voici mes recommandation/meilleures pratiques.

en utilisant // est mieux que /* */ car alors vous pouvez utiliser ce dernier pour retirer un bloc entier contenant d'autres commentaires. Toutefois, si vous souhaitez utiliser un outil de génération automatique de documentation, vous devez utiliser des commentaires similaires au style javaDoc.

Voici un exemple qui fonctionnerait avec DOC YUI (meilleur) http://developer.yahoo.com/yui/yuidoc/#start

/** 
* This is a description 
* @namespace My.Namespace 
* @method myMethodName 
* @param {String} str - some string 
* @param {Object} obj - some object 
* @param {requestCallback} callback - The callback that handles the response. 
* @return {bool} some bool 
*/ 
    function SampleFunction (str, obj, callback) { 
     var isTrue = callback(str, obj); // do some process and returns true/false. 
     return isTrue ; 
    } 

Autres params Exemples: - http://usejsdoc.org/tags-param.html

Source: -Does JavaScript have a standard for commenting functions?

En espérant que cette volonté vous aider :)

Answer 2

question difficile car il est en bas de vos préférences, vous devez également considérer d'autres développeurs ayant à lire votre code à l'avenir.

Je reçois personnellement un petit "commentaire fatigué" avec certaines approches, mais d'autres diront que vous ne pouvez pas commenter assez. Je pense qu'une bonne convention de nommage pour les fonctions et les variables peut souvent supprimer le besoin d'une grande majorité de commentaires.

Answer 3

Qu'est-ce que vous voulez faire est d'utiliser JSDoc pour une meilleure readabilty

/** 
* describe your function 
* @param {number} width - describe your parameter 
* @param {number} height - describe your parameter 
* @return {type} describe your returned value/object 
*/ 
function getCanvas(width = 200, height = 150) { 
    // code to run 
} 

c'est également très pratique avec votre IDE

Answer 4

Les commentaires sont bons pratics de programmation, de sorte que son, à mon avis , laissez le code plus propre. Par exemple, lorsque votre code a besoin de maintenance, l'autre programmeur le comprendra. Je pense que vous avez besoin de commenter ce que vous pensez nécessaire à d'autres pour comprendre et essayer d'être clair.