Comment écrire des commentaires sur les commits

Préface du traducteur

Au cours des années de développement de logiciels, en faisant partie de nombreuses équipes, en travaillant avec diverses personnes compétentes et expérimentées, j'ai souvent observé (et pour être honnête, j'ai créé) le même problème - un désordre total dans le référentiel. Chacun a écrit des commentaires sur les commits dans son propre style (et bien, si constamment dans un); la moitié des commentaires étaient inutiles (de la catégorie " c'est un pont "), la moitié de la moitié restante était à peine comprise.

Et puis un bon moment j'ai vu cet article, avant de mettre la main sur la traduction. Seules 7 règles simples et brèves, et voilà, regarder l'histoire des commits était non seulement utile, mais aussi agréable. Rien de révolutionnaire, tout est assez évident, mais formulé et résumé très bien.

Je veux noter qu'il s'agit d'un article de 2014. Certaines choses peu pertinentes mentionnées par l'auteur pourraient perdre de leur pertinence, mais l'essence de l'article ne l'est pas du tout.

Introduction: pourquoi les bons commentaires sont importants

Si vous regardez dans un référentiel Git aléatoire, vous constaterez très probablement qu'il y a une sorte de gâchis dans l'historique des validations. Par exemple, jetez un œil à ces perles depuis le moment où j'ai commencé à m'engager dans le référentiel Spring:

 $ git log --oneline -5 --author cbeams --avant "Fri Mar 26 2009"

 e5f4b49 Re-ajout de ConfigurationPostProcessorTests après sa brève suppression dans r814.  @ Ignorer la méthode testCglibClassesAreLoadedJustInTimeForEnhancement () car il s'avère que c'était l'un des coupables de la rupture récente de la construction.  Le piratage du chargeur de classe provoque des effets subtils en aval, rompant les tests non liés.  La méthode de test est toujours utile, mais ne doit être exécutée que manuellement pour garantir que CGLIB n'est pas chargé de classe prématurément et ne doit pas être exécuté dans le cadre de la génération automatisée.
 2db0f12 a corrigé deux problèmes révolutionnaires: + retour de ClassMetadataReadingVisitor à la révision 794 + élimination de ConfigurationPostProcessorTests jusqu'à ce qu'une enquête plus approfondie détermine pourquoi cela entraîne l'échec des tests en aval (tels que les ClassPathXmlApplicationContextTests apparemment sans rapport)
 147709f Modifications apportées aux fichiers package-info.java
 22b25e0 Classes Util consolidé et MutableAnnotationUtils en AsmUtils existants
 7f96f57 polishing

Horreur. Comparez avec ces commits plus récents dans le même référentiel:

 $ git log --oneline -5 --author pwebb --before "Sat Aug 30 2014"

 5ba3db6 Correction d'un échec de CompositePropertySourceTests
 84564a0 Rework @PropertySource early parsing logic
 e142fd1 Ajouter des tests pour les métadonnées ImportSelector
 887815f Mettre à jour la dépendance du docbook et générer epub
 ac8326d Utilisation du mockito polonais

Quelle option préférez-vous?

Les premiers varient en longueur et en style, les seconds sont concis et homogènes.
Le premier est obtenu par lui-même, le second est écrit consciemment.

Et bien que l'historique de validation de nombreux référentiels ressemble à la première option, il existe des exceptions. De bons exemples sont le noyau Linux et Git lui-même . Jetez un œil à Spring Boot ou à tout autre référentiel avec lequel Tim Pope s'occupe.

Les participants à ces projets savent qu'un commentaire bien écrit sur le commit est le meilleur moyen de décrire le contexte des modifications apportées aux autres développeurs (ainsi qu'à eux-mêmes à l'avenir). Les différences dans les révisions montrent ce qui a changé, mais seul un commentaire peut expliquer clairement pourquoi . Peter Hutterer l'a bien dit :

Récupérer du codage est une perte de temps. Nous ne pouvons pas l'éviter complètement, nos efforts doivent donc se concentrer sur la réduction de ces coûts. C'est à cela que servent les commentaires sur les commits. Par conséquent, ils montrent si le programmeur fonctionne bien en équipe.

Si vous n'avez pas vraiment pensé à ce que devrait être un commentaire de validation de premier ordre, vous n'avez probablement pas utilisé trop souvent git log et des outils similaires. Il y a un cercle vicieux: comme l'histoire des commits est non structurée et hétérogène, ils ne l'utilisent pas et n'y prêtent pas attention. Et du fait qu'ils ne l'utilisent pas et n'y prêtent pas attention, il reste non structuré et hétérogène.

Mais une histoire de référentiel bien conçue est une chose belle et utile. Les commandes git blame , revert , rebase , log , shortlog et autres prennent vie . Il est logique de regarder les commits et les pull pulls des autres et, soudain, l'aide de leurs auteurs n'est plus nécessaire. Pour comprendre pourquoi quelque chose s'est produit [dans le code] il y a des mois ou des années, cela devient non seulement possible, mais aussi pratique.

Le succès à long terme du projet dépend (entre autres) de la commodité de sa maintenance, et l'historique des validations est l'un des outils les plus puissants du mainteneur. Il vaut la peine de passer du temps à apprendre à y maintenir l'ordre. Au début, cela peut causer des inconvénients, mais ensuite cela deviendra une habitude et, à la fin, cela deviendra une source de fierté et de travail productif pour tous les participants.

Cet article ne traite que du composant le plus fondamental du maintien d'une bonne histoire, à savoir comment écrire un commentaire sur un commit séparé. Il y a d'autres choses importantes, comme la fusion des commits qui ne sont pas traitées ici.

La plupart des langages de programmation ont des conventions généralement bien décrites qui forment un style distinctif [d'écriture de code], comme les noms de variables, les règles de formatage, etc. Bien sûr, il existe différentes versions de ces accords, mais la plupart des développeurs sont d'avis que choisir une option et la suivre est bien mieux qu'un gâchis quand tout le monde écrit dans son propre style.

L'approche de l'équipe pour décrire les commits doit être exactement la même. Pour que l'histoire du référentiel soit utile, l'équipe doit se mettre d'accord sur au moins les trois points suivants.

Style. Syntaxe de balisage, indentation, sauts de ligne, grammaire, lettres majuscules, ponctuation. Vérifiez toujours votre orthographe et écrivez aussi facilement que possible. En conséquence, vous obtiendrez une histoire étonnamment complète des commits, qui est non seulement agréable à lire, mais que vous lirez vraiment régulièrement.

Le contenu Quelles informations devraient (le cas échéant) figurer dans le corps du commentaire? Pourquoi ne devrait - il pas être là?

Métadonnées Comment dois-je faire référence aux ID de tâche, aux numéros de demande d'extraction, etc.?

Heureusement, il existe déjà des accords pour rédiger un commentaire significatif. En fait, ils proviennent en partie du fonctionnement de certaines commandes Git. Vous n'avez pas besoin de réinventer la roue. Suivez simplement les sept règles ci-dessous - et vous vous rapprocherez de l'histoire des commits dignes d'un professionnel.

Sept règles pour un commentaire de commit sympa

N'oubliez pas: tout cela a déjà été dit .

1. Séparez l'en-tête du corps avec une chaîne vide
2. Limitez le titre à 50 caractères
3. Capitaliser le titre
4. Ne mettez pas de point à la fin du titre
5. Utilisez l'impératif dans le titre.
6. Aller à la ligne suivante du corps avec 72 caractères
7. Dans le corps, répondez aux questions de quoi et pourquoi , et non comment

Par exemple:

 Résumez les changements en 50 caractères ou moins

 Expliquez-les ici plus en détail, si nécessaire.  Suivi
 des sauts de ligne d'environ 72 caractères.  Dans certaines situations
 la première ligne du commentaire est considérée comme son titre, et 
 le reste est avec le corps.  Il est impératif de se séparer pour se séparer l'un de l'autre
 une chaîne vide (si le message a un corps, bien sûr);
 divers outils comme «log», «shortlog» et «rebase» ne comprendront pas
 vous si l'en-tête et le corps ne sont pas séparés.

 Expliquez ici le problème résolu par cette validation.  À emporter 
 plus d'attention à la raison pour laquelle vous avez apporté ces modifications, 
 exactement comment vous l'avez fait (cela vous expliquera le code).
 Y a-t-il des effets secondaires ou d'autres effets non évidents dans 
 ces changements?  Si oui, cela doit être expliqué ici.

 Les paragraphes sont séparés par des lignes vides.

  - Vous pouvez faire des listes à puces

  - Habituellement un astérisque ou 
    Un tiret avec un espace devant eux  mais il existe différents accords

 Si vous avez un outil de suivi des bogues [ou un système de gestion de projet],
 mettez les liens de tâche à la fin du texte de cette façon:

 Résolu: # 123
 Voir aussi: # 456, # 789

1. Séparez l'en-tête du corps avec une chaîne vide

Du manuel à la commande git commit :

Bien que cela ne soit pas nécessaire, il est judicieux de commencer un commentaire sur la validation avec une ligne courte (moins de 50 caractères) résumant les modifications apportées, puis une ligne vide et une description plus détaillée. Le texte avant la première ligne vide du commentaire est considéré comme l'en-tête du commit et est utilisé dans différentes commandes Git. Par exemple, Git-format-patch (1) transforme une validation en e-mail; l'équipe utilise l'en-tête du commit pour le sujet de la lettre et le reste du texte pour le corps de la lettre.

Tout d'abord, tous les commit ne nécessitent pas d'en-tête et de corps. Parfois, une ligne suffit, surtout lorsque les modifications sont si petites qu'aucune information supplémentaire à leur sujet n'est requise. Par exemple:

  Correction d'une faute de frappe dans l'introduction au guide de l'utilisateur 

Assez dit; si l'utilisateur veut savoir quel type de faute de frappe a été corrigé, il peut simplement regarder les changements eux-mêmes en utilisant git show ou git diff , ou git log -p .

Si vous validez quelque chose comme ça en utilisant la ligne de commande, il sera pratique d'utiliser l'option -m pour git commit :

  $ git commit -m "Correction d'une faute de frappe dans l'introduction au guide de l'utilisateur" 

Cependant, lorsque le commit mérite des explications et une description de la situation, vous devez les écrire dans le corps du commentaire. Par exemple:

 Derezz le programme de contrôle maître

 MCP s'est avéré être mauvais et était devenu déterminé à dominer le monde.
 Ce commit jette le disque de Tron dans MCP (provoquant sa dérésolution)
 et le transforme en jeu d'échecs.

Les commentaires qui ont un corps ne sont pas aussi pratiques à écrire avec l'option -m . Il serait préférable d'utiliser un éditeur de texte pour cela. Si vous n'avez pas encore configuré l'éditeur pour l'utiliser avec Git, lisez cette section du livre Pro Git .

Dans tous les cas, la séparation du titre et du corps du commentaire sera payante lors de la visualisation du journal. Voici le dossier de validation complet:

 $ git log
 commit 42e769bdf4894310333942ffc5a15151222a87be
 Auteur: Kevin Flynn <kevin@flynnsarcade.com>
 Date: ven 01 janv 00:00:00 1982 -0200

  Derezz le programme de contrôle maître

  MCP s'est avéré être mauvais et était devenu déterminé à dominer le monde.
  Ce commit jette le disque de Tron dans MCP (provoquant sa dérésolution)
  et le transforme en jeu d'échecs.

Et voici la commande git log --oneline , qui n'affiche que la ligne d'en-tête:

 $ git log --oneline
 42e769 Derezz le programme de contrôle maître

Ou git shortlog, que les groupes commettent par auteur, encore une fois, par souci de concision, ne montre que le titre:

 $ git shortlog
 Kevin Flynn (1):
       Derezz le programme de contrôle maître

 Alan Bradley (1):
       Introduire le programme de sécurité "Tron"

 Ed Dillinger (3):
       Renommez le programme d'échecs en "MCP"
       Modifier le programme d'échecs
       Mettre à niveau le programme d'échecs

 Walter Gibbs (1):
       Introduire le programme d'échecs de protoype

Il existe de nombreuses autres situations où il est nécessaire de faire la distinction entre l'en-tête et le corps du commit - et pour cela, ils doivent être séparés par une ligne vide.

2. Limitez le titre à 50 caractères

Techniquement, dépasser 50 caractères est possible, mais déconseillé. Cette longueur du titre garantit sa lisibilité et fait également réfléchir l'auteur à la formulation la plus concise et la plus claire pour décrire ce qui se passe.

Astuce: s'il vous est difficile de résumer les résultats du travail, peut-être qu'un commit contient trop de changements. Efforcez-vous de faire des commits atomiques (c'est un sujet pour un article séparé).

L'interface de GitHub prend clairement en charge ces conventions. Il vous avertira si vous dépassez la limite de 50 caractères:


Et coupez tous les en-têtes de plus de 72 caractères, en remplaçant une ellipse:


Visez donc 50 caractères, mais gardez à l'esprit que 72 est une restriction stricte.

3. Mettez le titre en majuscule

Ici, tout est simple. Mettez en majuscule toutes les rubriques.

Par exemple:

• Accélérez à 88 miles par heure

Au lieu de cela:

• accélérer à 88 miles par heure

4. Ne mettez pas de point à la fin du titre

Il n'y en a pas besoin. De plus, chaque personnage compte lorsque nous essayons d'en rencontrer 50.

Par exemple:

• Ouvrez les portes de la baie de pod

Au lieu de cela:

• Ouvrez les portes de la baie de pod.

5. Utilisez l'impératif dans le titre.

L'humeur impérative signifie littéralement: une forme de verbe exprimant une volonté (ordre, demande ou conseil). Quelques exemples:

• Nettoyez votre chambre (rangez la chambre)
• Ferme la porte
• Sortez la poubelle

Chacune des sept règles que vous lisez est écrite de manière impérative ("Aller à la ligne suivante du corps avec 72 caractères", etc.).

Cette forme peut sembler un peu grossière, et donc pas si souvent utilisée [en anglais - env. trans. ]. Mais il est parfait pour l'en-tête de validation. L'une des raisons est le fait que Git lui-même utilise l'impératif lorsqu'il s'engage en votre nom.
Par exemple, lors de l'utilisation de git merge, le message suivant sera ajouté par défaut:

 Fusionner la branche 'myfeature'

Et lorsque vous utilisez git revert :

 Revenir "Ajoutez la chose avec le truc"
	
 Cela annule la validation cc87791524aedd593cff5a74532befe7ab69ce9d.

Ou lorsque vous cliquez sur le bouton "Fusionner" dans l'interface de demande de pull sur GitHub:

 Fusionner la demande de tirage n ° 123 de someuser / somebranch

Ainsi, lorsque vous écrivez vos propres messages de commit dans l'état d'esprit impératif, vous suivez les règles établies dans Git lui-même. Par exemple:

• Refactor sous-système X pour la lisibilité
• Mettre à jour la documentation de démarrage
• Supprimer les méthodes obsolètes
• Version 1.0.0

Cette méthode peut à première vue sembler inconfortable. Nous sommes plus habitués à utiliser l'indicatif, qui est plus susceptible de rapporter des faits. Par conséquent, les messages de validation s'avèrent souvent être quelque chose comme ceci:

• Correction d'un bug avec Y
• Changer le comportement de X

Et parfois, les en-têtes décrivent simplement le contenu du commit:

• Plus de corrections pour les trucs cassés
• De nouvelles méthodes API douces

Il existe une règle simple qui vous permettra d'éviter les erreurs.

Un en-tête de validation correctement composé doit compléter la phrase suivante:

• S'il est appliqué, ce commit <en- tête de commit >

Par exemple:

• S'il est appliqué, ce commit remaniera le sous-système X pour plus de lisibilité
• S'il est appliqué, ce commit mettra à jour la documentation de démarrage
• S'il est appliqué, ce commit supprimera les méthodes obsolètes
• S'il est appliqué, ce commit publiera la version 1.0.0

S'il est appliqué, ce commit fusionnera la requête pull # 123 de l'utilisateur / branche

Assurez-vous que les verbes dans d'autres humeurs, non impératives, ne fonctionnent pas ici:

• S'il est appliqué, ce commit corrige un bug avec Y
• S'il est appliqué, ce commit changera le comportement de X
• S'il est appliqué, ce commit aura plus de correctifs pour les choses cassées
• S'il est appliqué, ce commit apportera de nouvelles méthodes API

N'oubliez pas: l'utilisation de l'impératif n'est importante que dans l'en-tête du commit. Dans le corps du commit, c'est facultatif.

6. Passez à la ligne suivante du corps avec 72 caractères

Git lui-même n'organise pas automatiquement les sauts de ligne. Lors de la modification du corps du commentaire, vous devez vous souvenir de la bordure droite et définir manuellement les sauts de ligne.

Il est recommandé de passer à la ligne suivante avec 72 caractères afin que Git puisse indenter et toujours contenir 80 caractères au total.

Un bon éditeur de texte peut vous y aider. Il est assez facile de configurer, disons, Vim, un saut de ligne de 72 caractères pour écrire un message dans une validation. Cependant, il se trouve que les IDE sont terriblement pauvres pour prendre en charge les sauts de ligne intelligents pour les validations de messages (bien que les dernières versions d'IntelliJ IDEA se soient finalement améliorées dans cette partie). ( environ. - peut-être pour le moment tout va beaucoup mieux ).

7. Dans le corps, répondez aux questions «quoi» et «pourquoi», pas «comment»

Ce commit du dépôt Bitcoin fournit une excellente explication de ce qui a changé et pourquoi.

 validation eb0b56b19017ab5c16c745e6da39c53126924ed6
 Auteur: Pieter Wuille <pieter.wuille@gmail.com>
 Date: ven.1 août 22:57:55 2014 +0200

    Simplifiez la gestion des exceptions de serialize.h

    Supprimez 'state' et 'exceptmask' du flux de serialize.h
    implémentations, ainsi que les méthodes associées.

    Comme exceptmask incluait toujours «failbit» et setstate était toujours
    appelé avec bits = failbit, il n'a fait que lever immédiatement un
    exception.  Débarrassez-vous de ces variables et remplacez setstate
    à l'exception des lancers directs (qui éliminent également certains morts
    code).

    Par conséquent, good () n'est jamais atteint après un échec (il y a
    seulement 2 appels, dont un en test), et peut être remplacé
    par! eof ().

    fail (), clear (n) et exceptions () ne sont tout simplement jamais appelés.  Effacer
    eux.

Regardez les changements dans le code et pensez au temps que l'auteur a économisé aux participants actuels et futurs du projet, en décrivant le contexte du travail effectué dans le commentaire. Sinon, il serait probablement perdu pour toujours.

Dans la plupart des cas, vous pouvez omettre les détails de la façon dont les modifications ont été apportées. Habituellement, le code parle de lui-même dans ce sens (et s'il est si complexe qu'une clarification est nécessaire, alors il y a des commentaires à ce sujet).

Concentrez-vous principalement sur l'explication des raisons pour lesquelles les changements ont été apportés - décrivez la situation avant le changement (et ce qui lui est arrivé), la situation après, et pourquoi vous avez choisi cette façon particulière de résoudre le problème.

Peut-être qu'à l'avenir, vous vous en remercierez!

Astuces

J'adore la ligne de commande. Oublié l'IDE.

Il existe de nombreuses raisons - par le nombre de commandes Git - d'utiliser la ligne de commande au maximum. Git est un outil incroyablement puissant; IDE - aussi, mais chacun à sa manière. J'utilise IntelliJ IDEA tous les jours, j'ai souvent dû faire affaire avec d'autres (par exemple, Eclipse), mais je n'ai jamais vu que l'intégration de Git dans l'IDE pouvait être comparée en termes de simplicité et de capacités à la ligne de commande (dès que vous la comprenez).

Certaines fonctionnalités de l'EDI pour le contrôle de version sont tout simplement inestimables, par exemple, l'exécution automatique de git rm lorsque vous supprimez un fichier, ou d'autres éléments git nécessaires lorsque vous le renommez. Mais c'est bien pire lorsque vous essayez de valider, fusionner, rebaser ou effectuer une analyse complexe de l'historique des validations à l'aide de l'EDI.

Lorsque vous devez déverrouiller le plein potentiel de Git, la ligne de commande est sans pareille.
N'oubliez pas que si vous utilisez Bash, Zsh ou Powershell - il existe des scripts pour exécuter des commandes qui vous évitent le besoin douloureux de se souvenir de toutes les sous-commandes et options.

Lire le livre Pro Git

Le magnifique livre Pro Git ( également en russe - environ la traduction ) est disponible gratuitement. Profitez-en!