Pour les commentaires sur le contrôle de version, que font / recommandent les autres utilisateurs - au passé ou au présent?

C'est à dire

• Modifié x en y.
• ou
• Changer x pour y.

Les commentaires doivent être lus dans leur contexte, donc:

Présent

Pour les commentaires source au-dessus d'une méthode, ou avant qu'un problème ne se produise:

// This function does X
function doX() { ... }

Passé

Pour les commentaires source après un certain comportement

function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ...
}

Et pour valider les messages

la fonction X a changé

Exemple mixte:

// This function does X
function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ....
}

Passé - Puisque quiconque le lira à l'avenir se référera à l'acte du changement comme cela s'est produit dans le passé.

Formuler quelque chose comme "Modification" implique que vous êtes actuellement en train d'effectuer la modification et que le code n'est peut-être pas terminé.

note: Personnellement, je ne mets de commentaires de modification que lorsqu'un changement radical s'est produit.

Les commentaires sont les choses statiques, donc ils devraient présenter l'état du programme comme il est , et non pas comme il va être. Pour répondre à votre question spécifique, il serait plus approprié d'utiliser le passé .

Cependant, ce type de commentaire est mieux adapté à votre système de contrôle de version. Le contrôle de version fait un bien meilleur travail de suivi des modifications que les commentaires manuels. Avec les systèmes de contrôle de version, il est plus approprié de documenter au présent car ces commentaires s'appliquent au moment où la modification est validée. Mais, l'un ou l'autre fonctionnera.

Je recommanderais fortement que les seuls commentaires dans votre code soient ce qui est nécessaire pour comprendre le code lui-même - le but, la logique métier et les cas exceptionnels. Laissez la documentation du jeu de modifications à votre système de contrôle de version. Si vous n'utilisez pas de VCS, commencez maintenant. Il existe plusieurs VCS de haute qualité gratuits (Subversion, Mercurial, Git, etc.).

J'utilise le présent impératif, donc quelque chose comme:

Remplacez «x» par «y»

Ceci est recommandé par les développeurs Git:

• le corps doit fournir un message de validation significatif, qui:
  • utilise l'impératif, le présent: "changer", pas "changé" ou "changements".

Cela peut sembler un peu étrange au début, mais si vous considérez un commit comme un patch qui fait quelque chose, cela a plus de sens. (Cela est particulièrement vrai dans un DVCS comme Git, où vous extrayez des changesets d'autres personnes qui agissent sur votre repo.)

Cela n'a pas vraiment d'importance; Je pense que c'est un style et une préférence personnels. Comme par écrit presque n'importe quoi, soyez juste cohérent avec vous-même et avec les autres commentaires.

Les commentaires du code doivent être naturels à lire.

Si vous lisez le code vous disant « Ce code est en train de faire X » alors vous devriez écrire le commentaire dans le temps présent comme il est probable que la façon dont une personne lisant le code à ce moment - là pensera aussi bien. Si de l'autre vous pensiez à un moment donné "Ce code a fait X", alors ça devrait être passé. En fin de compte, cela se résume à des préférences personnelles, sauf si pour une raison quelconque, vous êtes sous des directives sur la façon de commenter votre code (par exemple pour un projet d'équipe ou pour une classe, etc.)

Si vous utilisez git, la convention consiste à utiliser le temps présent car les messages de commit générés avec les outils git (par exemple la fusion) utilisent le temps présent.

Vous devez utiliser le passé.

La raison étant que vous répondez à la question à quoi cet engagement a-t-il abouti? Considérez-le comme disant à votre VCS ce que vous avez fait:

Commit 123
XYZ modifié pour faire ABC

Pour donner des contre-exemples, utiliser le futur donne l'impression que vous demandez à quelqu'un de le faire:

Commit 123
Changer XYZ pour faire ABC

et en utilisant le présent, on dirait que vous êtes à mi-chemin:

Commit 123
Changer XYZ pour faire ABC

Utilisez le temps présent: «Changer X en Y», presque comme s'il s'agissait d'un élément sur une liste TODO claire.

En général, tout comme un scénario, évitez les verbes comme "être" et "est". Par exemple, ce n'est pas «il marche», mais «il marche».

Mais dans cet exemple particulier - si vous parlez de commentaires de code, et non de commentaires d'enregistrement - je pense que "Changer X en Y" est un commentaire terrible. Il n'ajoute aucune nouvelle information, et si le code devait changer, il pourrait même être incorrect. Il vaut mieux extraire le code dans une méthode (ou une classe), puis documenter cette méthode à la place. Si c'est assez clair, alors un bon nom de méthode suffira.

En parlant de cela, pour documenter les méthodes, vous pourriez utiliser le futur, par exemple: "Si le nombre fourni est négatif, absretournera l'ampleur du nombre."

Les commentaires sont (ou devraient être), comme tout ce qui est écrit, des expressions de quelque chose, et ils devraient simplement suivre les mêmes règles dans les langues naturelles (en tenant compte des raccourcis et des abréviations spécifiques à la situation ou à l'artefact documenté.

Les commentaires sur le temps présent ( .ie "ça change" ou "ça change" ) indiquent qu'une donnée exploitée par l'algorithme documenté est affectée d'une manière ou d'une autre. C'est-à-dire qu'il indique ce que fait le code ou ce qui se passe pour les données manipulées.

Les commentaires au passé doivent indiquer une affirmation, une condition préalable ou une post-condition de quelque chose qui s'est produit avant le point où réside le commentaire. Par exemple:

L'entrée a déjà été validée avant de saisir ce bloc de code

ou

Des données ont été écrites dans un fichier à la fin de ce code en cours d'exécution

Les commentaires au passé peuvent également expliquer pourquoi quelque chose est fait ( cette fonction fait X et Y pour résoudre un problème avec la base de données héritée. )

Les commentaires au passé indiquant une modification du code lui-même (.ie. X a été remplacé par Y ) ne doivent pas exister dans le code. Ils devraient plutôt exister en tant que commentaires de révision dans le référentiel de code source.

À l'avenir, les commentaires devraient indiquer une condition qui doit être remplie ou traitée, mais qui, pour X ou Y, ne se fait pas pour le moment. Par exemple:

Lorsque nous migrerons finalement la base de données, nous devrons changer cette logique

ou

TODO: dès que possible, revisitez la validation de l'entrée - elle peut échouer pour le type d'entrée X ou Y, peut nécessiter des changements massifs qui ne peuvent pas être implémentés pour le moment.

Pour le type de commentaires TODO ultérieur , une autre forme de documentation doit exister pour garantir que ces modifications ont bien lieu. La dernière chose que vous voulez, ce sont des TODO perdus dans le temps et l'espace: P

Prenez-le avec un grain de sel, mais ce sont généralement les règles que je respecte habituellement lorsque je fais mes propres commentaires.

Commentant est sur la communication à l' être humain, donc en cohérence est importante, il est important ne pas nous enliser dans les principes lorsque les principes eux - mêmes obtenir de la manière d' une bonne communication. Cela dit, j'utilise les pseudo-normes suivantes:

• Les commentaires décrivant un comportement souhaité prennent la forme d'une phrase impérative au présent.

  // Calculate the width of the curve at x height.
  

• Utilisez un ensemble de mots clés tout en majuscules pour décrire les thèmes courants du codage (et pour faciliter la recherche):

  // NOTE: <This code was written this way for a reason.>
  // TODO: <This code is incomplete. Finish it.>
  // HACK: <This code was written this way for a reason that you won't like.>
  // FIXME: <This code has a known flaw. Fix it.>