Le code commenté peut-il être une documentation précieuse?

J'ai écrit le code suivant:

if (boutique == null) {
    boutique = new Boutique();

    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.persist(boutique);
} else {
    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    //boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.merge(boutique);
}

Il y a une ligne commentée ici. Mais je pense que cela rend le code plus clair en précisant la différence entre ifet else. La différence est encore plus marquée avec la mise en surbrillance des couleurs.

Commenter un code comme celui-ci peut-il être une bonne idée?

La plupart des réponses se concentrent sur la façon de reformuler ce cas spécifique, mais permettez-moi de donner une réponse générale à la raison pour laquelle le code commenté est généralement mauvais:

Tout d'abord, le code commenté n'est pas compilé. C'est évident, mais cela signifie que:

1. Le code pourrait même ne pas fonctionner.

2. Lorsque les dépendances du commentaire changent, cela ne va évidemment pas casser.

Le code commenté est très "code mort". Plus il reste assis longtemps, plus il pourrit et fournit de moins en moins de valeur au prochain développeur.

Deuxièmement, l'objectif n'est pas clair. Vous avez vraiment besoin d'un commentaire plus long qui fournisse un contexte expliquant pourquoi il existe des lignes commentées de manière aléatoire. Lorsque je ne vois qu'une ligne de code commentée, je dois chercher comment cela est arrivé pour comprendre pourquoi il est arrivé là. Qui l'a écrit? Quel commit? Quel était le message / contexte de validation? Etc.

Envisager des alternatives:

• Si l'objectif est de fournir des exemples d'utilisation d'une fonction / API, fournissez un test unitaire. Les tests unitaires sont du code réel et ne fonctionneront plus quand ils ne seront plus corrects.
• Si le but est de conserver une version précédente du code, utilisez le contrôle de code source. Je préférerais de beaucoup extraire une version précédente, puis basculer les commentaires dans la base de code pour "annuler" un changement.
• Si le but est de conserver une autre version du même code, utilisez le contrôle de source (à nouveau). C'est à cela que servent les branches, après tout.
• Si le but est de clarifier la structure, réfléchissez à la manière dont vous pouvez restructurer le code pour le rendre plus évident. La plupart des autres réponses sont de bons exemples de la manière dont vous pourriez le faire.

Le plus gros problème avec ce code est que vous avez dupliqué ces 6 lignes. Une fois que vous avez éliminé cette duplication, ce commentaire est inutile.

Si vous créez une boutiqueDao.mergeOrPersistméthode, vous pouvez la réécrire comme suit:

if (boutique == null) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

boutiqueDao.mergeOrPersist(boutique);

Le code qui crée ou met à jour un certain objet est commun, vous devez donc le résoudre une fois, par exemple en créant une mergeOrPersistméthode. Vous ne devez certainement pas dupliquer tout le code de mission pour ces deux cas.

De nombreux ORM ont construit un support pour cela d'une certaine manière. Par exemple, ils peuvent créer une nouvelle ligne si la valeur idest zéro et mettre à jour une ligne existante si la valeur idest différente de zéro. La forme exacte dépend de l'ORM en question, et comme je ne connais pas bien la technologie que vous utilisez, je ne peux pas vous aider.

Si vous ne souhaitez pas créer de mergeOrPersistméthode, vous devez éliminer la duplication d'une autre manière, par exemple en introduisant un isNewBoutiqueindicateur. Cela n’est peut-être pas beau, mais c’est quand même bien mieux que de dupliquer toute la logique d’attribution.

bool isNewBoutique = boutique == null;
if (isNewBoutique) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

if (isNewBoutique)
    boutiqueDao.persist(boutique);
else
    boutiqueDao.merge(boutique);

C'est une idée absolument horrible . Cela n'indique pas clairement l'intention. Le développeur a-t-il commenté la ligne par erreur? Pour tester quelque chose? Que se passe-t-il?!

Mis à part le fait que je vois 6 lignes qui sont absolument égales dans les deux cas. Au lieu de cela, vous devriez empêcher cette duplication de code. Il sera alors plus clair que dans un cas, vous appelez en outre setSelected.

Non, c'est une idée terrible. En me basant sur ce code, les pensées suivantes me viennent à l’esprit:

• Cette ligne est commentée car le développeur la déboguait et a oublié de restaurer la ligne à son état antérieur.
• Cette ligne est commentée car elle faisait autrefois partie de la logique métier, mais ce n'est plus le cas
• Cette ligne est commentée car elle posait des problèmes de performances en production et le développeur souhaitait voir quel était son impact sur un système de production.

Après avoir vu des milliers de lignes de code commenté, je fais maintenant la seule chose sensée quand je le vois: je le supprime immédiatement.

Il n'y a aucune raison valable pour archiver le code commenté dans un référentiel.

En outre, votre code utilise beaucoup de duplication. Je vous suggère d’optimiser cela le plus rapidement possible pour la lisibilité humaine.

Je voudrais juste ajouter à la réponse de CodesInChaos, en précisant que vous pouvez le reformuler davantage en petites méthodes . Le partage de fonctionnalités communes par composition évite les conditions:

function fill(boutique) {    
  boutique.setSite(site);
  boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
  boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
  boutique.setNom(fluxBoutique.getNom());
  boutique.setIdWebSC(fluxBoutique.getId());
  boutique.setDateModification(new Date());
}    

function create() {
  boutique = new Boutique();      
  fill(boutique);
  boutique.setSelected(false);
  return boutiqueDao.persist(boutique);
}

function update(boutique) {
  fill(boutiquie);
  return boutiquieDao.merge(boutique); 
}

function createOrUpdate(boutique) {
  if (boutique == null) {
    return create();
  }
  return update(boutique);  
}

Bien que ce ne soit clairement pas un cas valable pour un code commenté, il existe une situation qui, à mon avis, le justifie:

// The following code is obvious but does not work because of <x>
// <offending code>
<uglier answer that actually does work>

C'est un avertissement à ceux qui le verront plus tard que l'amélioration évidente ne le soit pas.

Edit: Je parle de quelque chose de petit. Si c'est grand, vous expliquez plutôt.

Dans cet exemple spécifique, je trouve le code commenté très ambigu, en grande partie pour les raisons exposées dans la réponse de Dibkke . D'autres ont suggéré des moyens de reformuler le code pour éviter même la tentation de le faire. Toutefois, si cela n'est pas possible pour une raison quelconque (par exemple, les lignes sont similaires, mais pas assez proches), j'apprécierais un commentaire du type:

// Inutile de désélectionner cette boutique, car [WHATEVER]

Cependant, je pense qu'il y a des situations où laisser (ou même ajouter du code commenté) n'est pas répréhensible. Lorsque vous utilisez quelque chose comme MATLAB ou NumPY, on peut souvent écrire un code équivalent qui 1) effectue une itération sur un tableau, en traitant un élément à la fois ou 2) exploite tout le tableau à la fois. Dans certains cas, le dernier est beaucoup plus rapide, mais aussi beaucoup plus difficile à lire. Si je remplace un code par son équivalent vectorisé, j'intègre le code d'origine dans un commentaire proche, comme ceci:

%% Le code vectorisé ci-dessous fait ceci:

% for ii in 1:N
%    for jj in 1:N
%      etc.

% mais la version de la matrice est environ 15 fois plus rapide avec une entrée typique (MK, 03/10/2013)

Évidemment, il faut veiller à ce que les deux versions fassent la même chose et que le commentaire reste synchronisé avec le code réel ou est supprimé si le code change. Évidemment, les mises en garde habituelles concernant l'optimisation prématurée s'appliquent également ...

La seule fois où j'ai vu du code de commentaire utile était dans les fichiers de configuration, où le code de chaque option est fourni, mais mis en commentaire, ce qui facilite l'activation des paramètres en supprimant simplement les marqueurs de commentaire:

## Enable support for mouse input:
# enable_mouse = true

Dans ce cas, le code commenté aide à documenter toutes les options disponibles et leur utilisation. Il est également classique d'utiliser les valeurs par défaut dans l'ensemble, de sorte que le code documente également les paramètres par défaut.

De manière générale, le code est auto-documenté uniquement par la personne qui l'a écrit. Si de la documentation est requise, écrivez-la. Il est inacceptable de s'attendre à ce qu'un nouveau développeur dans une base de code source lise des milliers de lignes de code pour tenter de comprendre ce qui se passe à un niveau élevé.

Dans ce cas, la ligne de code commentée a pour but de montrer la différence entre deux instances de code en double. Au lieu d'essayer de documenter subtilement la différence avec un commentaire, réécrivez le code pour le rendre logique. Ensuite, si vous estimez toujours nécessaire de commenter le code, écrivez un commentaire approprié.

Non, le code commenté devient obsolète et devient vite pire que rien, il est souvent néfaste, car il cimente certains aspects de la mise en œuvre, ainsi que toutes les hypothèses actuelles.

Les commentaires doivent inclure les détails de l'interface et la fonction souhaitée. "fonction souhaitée": peut inclure, nous essayons d'abord, puis nous essayons cela, puis nous échouons de cette façon.

Les programmeurs que j'ai vus essaient de laisser des choses dans les commentaires sont juste en amour avec ce qu'ils ont écrit, ne veulent pas le perdre, même si cela n'ajoute rien au produit fini.

Cela peut être très rare, mais pas comme vous l'avez fait. Les autres réponses ont assez bien expliqué les raisons.

L'un des rares cas est une spécification de modèle RPM que nous utilisons dans ma boutique comme point de départ pour tous les nouveaux packages, principalement pour s'assurer que rien d'important n'est laissé de côté. La plupart de nos paquets, mais pas tous, ont une archive contenant des sources qui porte un nom standard et qui est spécifiée par une balise:

Name:           foomatic
Version:        3.14
 ...
Source0:        %{name}-%{version}.tar.gz

Pour les packages sans source, nous commentons la balise et la plaçons au-dessus pour conserver le format standard et indiquer que quelqu'un s'est arrêté et a réfléchi au problème dans le cadre du processus de développement:

Name:           barmatic
Version:        2.71
 ...
# This package has no sources.
# Source0:        %{name}-%{version}.tar.gz

Vous n'ajoutez pas de code dont vous savez qu'il ne sera pas utilisé car, comme d'autres l'ont déjà expliqué, il pourrait être confondu avec quelque chose qui y appartient. Ça peut. Cependant, il serait utile d’ajouter un commentaire expliquant pourquoi le code attendu est manquant:

if ( condition ) {
  foo();
  // Under most other circumstances, we would do a bar() here, but
  // we can't because the quux isn't activated yet.  We might call
  // bletch() later to rectify the situation.
  baz();
}

Le code commenté n'est pas utilisé par l'application, il doit donc être accompagné de commentaires supplémentaires expliquant pourquoi il n'est pas utilisé. Mais dans ce contexte, il existe des situations où le code commenté peut être utile.

Ce qui me vient à l’esprit est le cas où vous résolvez un problème en utilisant une approche commune et attrayante, mais il s’avère que les exigences de votre problème actuel sont légèrement différentes de ce problème. En particulier, si vos besoins nécessitent considérablement plus de code, les responsables de la maintenance auront la tentation d'optimiser le code en utilisant l'ancienne approche, mais cela ne fera que ramener le bogue. Garder la "mauvaise" implémentation dans les commentaires aidera à dissiper cela, car vous pouvez l'utiliser pour illustrer exactement pourquoi cette approche est erronée dans cette situation.

Ce n'est pas une situation que je peux imaginer arriver très souvent. En général, il devrait suffire d’expliquer les choses sans inclure un exemple de "mauvaise" mise en oeuvre. Mais je peux imaginer un cas où cela ne suffira pas, alors puisque la question est de savoir si cela peut être utile, oui. Juste pas la plupart du temps.

Cela ne semble pas bon mon pote.

Le code commenté est ... mais pas du code. Le code est pour la mise en œuvre de la logique. Rendre un code plus lisible en soi est un art. Comme @CodesInChaos a déjà suggéré que les lignes de code répétitives ne sont pas une très bonne implémentation de la logique .

Pensez-vous vraiment qu'un vrai programmeur préférera la lisibilité à une implémentation logique? (en passant, nous avons des commentaires et des «compléments» à mettre dans notre représentation logique).

En ce qui me concerne, on devrait écrire un code pour le compilateur et c'est bien - si "ça" le comprend. Pour la lisibilité humaine Les commentaires sont bons, pour les développeurs (à long terme), pour les personnes réutilisant ce code (par exemple, les testeurs).

Sinon, vous pouvez essayer quelque chose de plus flexible ici, quelque chose comme

boutique.setSite (site) peut être remplacé par

setsiteof.boutique (site). Il existe différents aspects et perspectives de la programmation orientée objet pour améliorer la lisibilité.

Bien que ce code semble être très attrayant au début et qu'on peut penser qu'il a trouvé un moyen de lisibilité humaine, le compilateur fait également son travail à la perfection. Nous commençons tous à suivre cette pratique, ce qui aboutira à un fichier flou qui deviendra moins lisible. dans le temps et plus complexe que cela va se développer.