web-dev-qa-db-fra.com

Comment éviter les commentaires sur une ligne de code pour la propreté

J'essaie de nettoyer une partie de mon code en utilisant quelques meilleures pratiques et de lire que les commentaires sont presque toujours une mauvaise idée de la maintenabilité future. J'ai réussi à vous débarrasser de la plupart d'entre eux en refactorisant les méthodes avec de bons noms.

Cependant, plusieurs commentaires sont assombris autour de cela expliquent pourquoi une seule ligne de code doit exister. J'ai du mal à comprendre un moyen de me débarrasser de ceux-ci. Ils suivent souvent ce genre de structure:

// Needs to start disabled to avoid artifacts the first frame. Will enable after frame complete.
lineRenderer.enabled = false;

Ensuite, plus tard dans le code, je l'active.

J'ai pensé à l'extraire dans une méthode d'une ligne appelée StartLineRendererDisabledToAvoidArtifactsFirstFrame() mais cela ne semble pas tout ce qui est propre pour moi.

Y a-t-il des meilleures pratiques pour traiter de tels doublures? Beaucoup d'entre eux expliquent l'existence du code que sur la surface a l'air superflu, mais a alors une fonction importante. Je veux me garder contre la suppression future.

Sidenote: J'ai déjà rencontré certains scénarios où refactoring/renommage a rendu ces commentaires sont obsolètes ou au mauvais endroit, etc. Donc, je vois certainement pourquoi les supprimer serait utile.

Question associée mais différente ici:

Modifier en fonction des réponses et des commentaires ci-dessous

Voici mon emporter de toutes les grandes discussions ci-dessous.

  1. Les commentaires vont bien s'il n'y a pas de moyen facile de refactoriser/renommer pour plus de clarté. Mais ils devraient être utilisés avec parcimonie.
  2. Supprimer des commentaires est généralement une bonne chose. Mais certains commentaires doivent exister pour aider les futurs lecteurs à comprendre le code sans avoir à creuser trop profond.
  3. Mais ils devraient expliquer le pourquoi, pas le comment.
  4. Si le code est là pour une raison particulière qui est très important ou corrige un bogue, il devrait probablement aussi avoir un test d'unité correspondant de toute façon.
  5. Les messages de validation peuvent aider à suivre pourquoi et comment et comment le code commenté est venu être.
clean-codecomments
66
Adam B

Juste une suggestion que je n'ai pas encore vue ici. J'écris habituellement mon code initial sans beaucoup de commentaires, mais chaque fois que j'ai une raison de revenir/re-lire le code (je fais habituellement plusieurs fois quand je l'écrivais initialement) si je rencontre n'importe quel code qui est difficile à comprendre Soit le refacteur, ajouter des commentaires ou améliorer les commentaires - tout ce qu'il faut pour que la prochaine fois que je ne devrai pas arrêter ici pour le comprendre. Le code d'écriture est comme n'importe quel processus de création, vous devez avoir un brouillon, faire des tests, le faire fonctionner, le nettoyer, la rendre compréhensible, etc. Chacune de ces activités est de retour et de réaffectation de ce que vous avez déjà fait. Il est itératif et une partie de ce processus itératif devrait être de s'assurer que cela est aussi simple que possible de comprendre.

Un problème à considérer si - la plupart des programmeurs ne font pas confiance aux commentaires suffisants pour même les lire. Si vous commencez bien et faites attention, vous constaterez que vous avez demandé des questions qui sont déjà clairement répondues dans les commentaires. Je ne sais pas comment aborder cela, alors j'écris des commentaires pour moi-même et quand ils me posent des questions sur mon code, même si je ne me souviendrai pas de ce que j'ai fait, je fais confiance à la réponse sera là dans un commentaire et je peux Regarde-le et y répondre.

0
Bill K

Comme beaucoup l'ont dit, des commentaires qui expliquent pourquoi plutôt que quoi sont généralement une bonne idée. Votre exemple est un exemple parfait d'un commentaire qui explique pourquoi un peu évident de code existe.

Si vous avez cette ligne exacte de code et une copie du commentaire, dans plusieurs endroits, il serait logique de créer une fonction à une doublure afin d'éviter la répétition.

Si cette ligne n'est pas au même niveau conceptuel que le code environnant, vous voudrez peut-être aussi l'isoler. Par exemple, si les déclarations précédemment et après avoir renversé ce drapeau sont des concepts de très haut niveau, la nécessité de l'expliquer avec un commentaire pourrait être un symptôme de travailler au mauvais niveau d'abstraction.

Considérez ce contexte hypothétique:

CommitRenderingContext(blah, blah, blah);
PrecalculateLookUpTable(parameters);

// Needs to start disabled to avoid artifacts the first frame. Will enable after frame complete.
lineRenderer.enabled = false;

lineRenderer.RenderFrames(frame_count);

Le fait que la seule doublure soit la seule déclaration dans les environs qui a besoin d'explication est un indice qu'il est hors de propos dans le contexte des travaux de niveau supérieur en cours. Vraisemblablement, la linerenderer sera activée à l'intérieur d'une boucle cachée Index Renderframes, ce qui signifie que les deux endroits qui se détachent ce drapeau ne sont pas seulement séparés par la distance, mais également par le niveau conceptuel. Dans ce cas, cela appartient probablement à l'intérieur de la méthode des rendants et le commentaire serait probablement très approprié là-bas.

Si, d'autre part, le contexte est quelque chose comme:

lineRenderer.color = user_selected_color;

// We use half the desired thickness because we're going to do two passes.
lineRenderer.thickness = user_selected_thickness / 2;

// Needs to start disabled to avoid artifacts the first frame. Will enable after frame complete.
lineRenderer.enabled = false;

for (int i = 0; i < frame_count; ++i) {
    ... detailed calculations ...
    if (lineRenderer.enabled) {
        ... do something with lineRenderer ...
    } else {
        lineRenderer.enabled = true;
    }
}

Ensuite, je ne considérerais pas le commentaire hors de la place.

0
Adrian McCarthy