Les commentaires à la première personne sont-ils distrayants et peu professionnels?


63

Je viens juste de me retrouver à écrire le commentaire suivant dans un code (archaïque Visual Basic 6.0) que j'écrivais:

If WindowState <> 1 Then
    'The form's not minimized, so we can resize it safely
    '...
End if

Je ne suis pas sûr de savoir pourquoi j'utilise inconsciemment "nous" dans mes commentaires. J'imagine que c'est parce que j'imagine que quelqu'un parcourt le code, comme s'il «exécutait» en réalité toutes les commandes de chaque ligne, plutôt que de simplement les regarder se dérouler. Avec cet état d'esprit, j'aurais pu l'utiliser I can resize it, puisque c'est moi qui le "fais" actuellement, ou you can resize it, comme si je parlais à qui le "faisait" à l'avenir, mais puisque ces deux cas vont très probablement arrive, j'utilise "nous" comme si je conduisais quelqu'un d'autre à travers mon code.

Je peux simplement réécrire au fur it can be resizedet à mesure et éviter le problème, mais cela a éveillé ma curiosité: est-il courant d'utiliser ce mot à la première personne dans les commentaires, ou est-ce considéré comme une distraction et / ou un manque de professionnalisme?


1
Commentaires pour le vote négatif? C’est ma première question sur Programmers.SE, et j’essaie toujours de comprendre exactement ce qui fait une bonne question P.SE par rapport à une bonne question SO.
dlras2

2
Je ne vous ai pas retenu le vote, mais je suppose qu'ils n'ont pas aimé la question du titre, car les réponses à cette question pourraient facilement être brèves, bavardes et trop confiantes à une opinion sans réserve. Reformuler cela pour qu'il ressemble davantage à votre dernière question pourrait aider.
DKnight

56
J'aime le "nous". Son amical et inclusif dans un genre sain, folklorique.
Jeremy

25
Je pense que je vais commencer à commenter toutes les corrections de bogues sur lesquelles je travaille à la troisième personne, omniscient. Cela devrait me rendre populaire au bureau ... "John ne savait pas que son ajout mal conçu ignorerait toujours ce code, laissant les utilisateurs perplexes. par le champ d'affichage toujours vide ... "
DKnight

4
C’est tout ce que je peux faire pour que mes commentaires ne contiennent pas de fautes de frappe. Maintenant, je dois me demander si la voix passive doit être utilisée ou non. Ensuite, je devrai veiller à ne pas suspendre les prépositions. J'imagine que c'est quelque chose que mes collègues ne supporteront peut-être pas. Et je suppose que je ne serai jamais autorisé à utiliser un infinitif divisé. Fragments de phrase?
Michael Burr

Réponses:


103

Les commentaires doivent être écrits pour que les êtres humains comprennent. Lorsque des êtres humains communiquent, nous utilisons généralement "je", "nous", "vous", etc.

Lorsque quelqu'un essaie de comprendre un code, il y a deux acteurs ou plus: la personne qui le lit et l'auteur original du code. Dire "nous" c'est bien. Sauf si vous faites référence à «professionnel», vous voulez dire «semblable à un robot».


3
+1 comme l'écriture de cette façon vous encourage l'écrivain à considérer le lecteur potentiel et cela peut vraiment vous aider à voir les concepts sur lesquels il pourrait être nécessaire de mieux s'expliquer.
Justin Ohms

64
// we approve of this answer:)
Jarrod Dixon

3
+1 et une amplification: au contraire, les constructions de voix passive comme "il peut être redimensionné" sont généralement rejetées par écrit car nous les trouvons difficiles à comprendre. Si vous utilisez la voix passive, vous obligez votre lecteur à inventer et à mémoriser un sujet pour la phrase.
msw

1
@msw: cela ne devrait-il pas être "nous rejetons les constructions de voix passive comme" il peut être redimensionné "..." alors?
tdammers

2
@msw, en russe par exemple, les concepts de voix passive sont plus courants et sont mieux compris en raison de certaines différences culturelles. (Et non, je n'ai pas fait exprès d'écrire cette phrase à voix passive!)
P Shved

22

Je suggérerais de ne pas utiliser "I" car il assume automatiquement toute la responsabilité du code. Si d'autres personnes le lisent, cela semblerait mauvais parce que, dans ce cas, il s'agit d'un effort d'équipe. Je suis indifférent à l'utilisation de «nous». Cela peut toutefois sembler inclure d'autres lecteurs de manière non authentique.

Mon vote va toujours pour la brièveté et la concision. Si le message peut être transmis de manière moins verbeuse, pourquoi choisir autre chose? Donc, concernant cet exemple, je voudrais écrire:

'The form is not minimized so it can be resized safely.

4
"Si le message peut être transmis de manière moins verbeuse, pourquoi choisir autre chose?" En tant que personne qui a dû se cogner contre le mur en essayant de mettre en œuvre les bibliothèques mal documentées de quelqu'un - les bibliothèques à code source libre sont notoires pour cela - je dis que je préférerais de loin avoir trop de commentaires que trop peu. Je pense que je suis d’accord avec vous si, si vous voulez dire, utilisez de bonnes phrases avec une ponctuation correcte qui a du sens.
Jonathan Henson

3
+1 pour ne pas assumer toutes les responsabilités dans une équipe. Et même si je suis d’accord pour essayer d’éviter les commentaires verbeux, parfois le temps passif peut être encore plus difficile à lire (comme l’a souligné jkj) et pas moins bavard, et je préfère éviter l’obscurcissement. =]
dlras2 le

2
@ Jonathan Henson: Beaucoup de commentaires sont bons, mais seulement s'ils contiennent beaucoup d'informations utiles. Si la même quantité d'informations peut être exprimée de deux manières équivalentes, la plus courte est la meilleure.
tdammers

Mon conseil est d'éviter d'utiliser la voix passive. C'est plus difficile à comprendre, surtout pour les non anglophones.
Ville Laurikari

18

Je prends l’une des deux approches, généralement ce qui me semble le mieux.

En expliquant des choses telles que les exigences ou la justification, je vais avec "nous" comme vous l'avez là:

// We can't proceed unless the user has given us this information.

Si j'explique le processus, j'ai tendance à utiliser une voix impérative (corrigez-moi si c'est le mauvais terme):

// Get the foo from bar and make sure it follows our required format.

Ce dernier peut être dangereusement proche de répéter le code, mais il y a des utilisations. Donc, ce n’est pas en utilisant I ou nous, mais en réalité cela implique "vous".


C'est exactement mon style aussi. Les deux manières que vous décrivez ont leur place.
Zourtney

9
Ce dernier a aussi "notre". Je trouve intéressant que les gens écrivent naturellement des commentaires à la première personne du pluriel.
Reid le

@ Reid wow ouais c'était juste l'instinct, je n'ai même pas remarqué. Mais il aurait simplement pu facilement dire "le".
Tesserex

8

Je pense que c'est juste une variation du style d'écriture académique / technique, qui est souvent impersonnel. En utilisant la voix passive, en utilisant le "nous royal" ("un" est tellement daté).

En règle générale, il n’est pas précis de savoir qui l’utilisera de toute façon - le commentaire est destiné aux responsables de la maintenance, et non normalement à l’auteur original.

Cela dit, j'utilise souvent la première personne dans les commentaires pour expliquer pourquoi j'ai pris des décisions particulières et ce que je pensais.


3
Personnellement, je ne pense pas que "l'un" est daté. Oui, il est moins utilisé, car ce n’est pas quelque chose que l’on utilise de temps en temps. Toutefois, il y a peu de chance pour que l'utilisation de "un" dans le sens d'un commentaire ne soit pas lisible ou ne nuise à la convivialité.
Billy ONeal

7

Les commentaires devraient vous expliquer pourquoi quelque chose est fait, pas ce qui est fait. Si ce que vous faites n'est pas évident dans le code, corrigez-le, ne vous contentez pas d'ajouter un commentaire. Peu importe la première personne, la deuxième personne, etc., l’important est de communiquer les informations nécessaires.

Si vous devez décrire le code, préférez les impératifs, par exemple

'ensure that the window is not minimized
If WindowState <> 1 Then
    'resize the window
    '...
End if

(Et s'il vous plait, n'utilisez pas de constantes nues comme "1" dans le code)


3
+1 pour préférer impératif, je n'avais pas pensé à cela. Aussi, oui, je n'aurais pas dû utiliser le nu 1. Je suis généralement assez doué pour ça ... Laissez-moi le soin de poster l'une des rares fois où cela m'a échappé l'esprit sur Internet.
dlras2

6

Peut-être parlons - nous des petits gars du programme qui font que la magie opère? :)

La voix passive en anglais est difficile à utiliser et sonne mal. Les gens aiment utiliser des formulaires personnels (moi, vous, nous, un).

Exemple:

(Vous / nous / on doit) utiliser un délégué pour transmettre les événements de redimensionnement de fenêtre au parent

Un délégué doit être utilisé pour transmettre les événements de redimensionnement de fenêtre à parent

Autre exemple (notez que vous pouvez souvent omettre les formulaires de personne dans les commentaires):

(Nous) attrapé une exception. (Nous serons) montrant un dialogue d'erreur.

Une exception a été interceptée et une boîte de dialogue d'erreur s'affiche.

PS Le remplacement de passive par "you" est si courant en anglais qu'il a également commencé à s'infiltrer dans d'autres langues. Cela semble extrêmement amusant, par exemple en finnois, où existe la forme singulière à la deuxième personne (comme le "tu" en anglais).


Je pense que linguistiquement ce n'est pas correct. Le premier est l'impératif, il n'a pas de sujet. "S'il vous plaît fermer la porte." Bien que cela signifie à peu près la même chose que "s'il vous plaît, pouvez-vous fermer la porte?" c'est une forme grammaticale distincte, pas une abréviation. Dans le deuxième exemple, vous pourriez aussi bien dire "(Il a) attrapé une exception. (Ce sera) en affichant une boîte de dialogue d'erreur."
Inca

3

Si vous parlez de l'exécution du programme, ce n'est pas «nous», «vous» ou «je». L’anthropomorphisme est peut-être si répandu qu’il est invisible, mais c’est une habitude dangereuse (PDF Warning. Dijkstra Warning.):

Je pense que l'anthropomorphisme est le pire de tous. J'ai maintenant vu des programmes "essayer de faire des choses", "vouloir faire des choses", "croire que les choses sont vraies", "savoir des choses", etc. Ne soyez pas assez naïf pour croire que cet usage du langage est inoffensif. Il invite le programmeur à s'identifier avec l'exécution du programme et lui impose presque l'utilisation de la sémantique opérationnelle.


2
Avertissement Dijkstra! Si seulement plus de choses en avaient un :(
Tom Anderson

Je ne pense pas que écrire des commentaires à la première personne du pluriel soit un anthropomorphisme. Je pense que cela implique: "Nous demandons maintenant à l'ordinateur de ...", comme si le programmeur qui écrivait le commentaire guidait le lecteur dans son code.
Blujay

2

Je ne pense pas que la première personne ou le «royal nous» semble peu professionnel ou distrayant. Je pense que nous devrions faire un effort pour écrire des commentaires en anglais dans E-Prime , le sous-ensemble de l'anglais qui ne possède pas le verbe "to be".

Si vous sur-utilisez "être" dans les commentaires, vous obtiendrez des déclarations confuses telles que:

// X is 10
// X is the user data of the newly-authenticated user
// X is a BigInt

Eh bien, peut-être pas tout à la fois, mais le principe d'égalité peut vraiment rendre les commentaires peu clairs.

Je pense que les exigences écrites dans E-Prime aident à clarifier ces exigences, car l'auteur doit indiquer un acteur en même temps que l'action.


Notion intéressante; comment exprimer les notions de "X devrait être au moins 5" ou "Y ne doit pas être supérieur à 23"?
Supercat

@supercat - "La valeur de X doit avoir une magnitude supérieure ou égale à 5". "La valeur de Y ne doit pas dépasser 23". L'égalité, logique ou arithmétique, ne devrait pas non plus utiliser le verbe "être". "X doit contenir 5" ou "X est évalué à 5" ou "X a la valeur 5" ou à peu près. Si vous rencontrez un commentaire particulièrement flou, recherchez les verbes "d’être". Je parie que ce commentaire peu clair utilise notant mais "être" verbes. Notez également que j'ai écrit la réponse ci-dessus dans E-Prime.
Bruce Ediger

La seconde va bien; le premier pas tellement, puisque -6 a une magnitude de 5 ou plus.
Supercat

@supercat - très bien. "X doit avoir un entier signé de 5 ou plus". Aux États-Unis, nous appellerions votre "magnitude" "valeur absolue", ce qui renforce mon propos de décrire la valeur d'une variable, et non la variable en tant que valeur, qui découle de l'is-d'égalité.
Bruce Ediger

2

Le style correct pour commenter est la troisième personne impersonnelle; " Le formulaire n'est pas minimisé, il peut donc être redimensionné en toute sécurité ".

  • Je suis naïf.
  • Vous est grossier.
  • Nous est trop formel (et royal).

Chaque phrase peut être reformulée de la manière suivante (voir ci-dessus) et c'est la seule manière professionnelle d'écrire.


11
-1 parce que: il n'y a pas de chemin correct, je trouve votre résumé de I / You / We un peu en retrait et je ne comprends pas la dernière partie. À côté: quand je dis "nous" dans mes commentaires, je n'essaie pas de parler comme un roi - je vous parle, le gars qui lit mon code et vous guide dans mes pensées côte à côte.
doppelgreener

2

Cela dépend du commentaire.

En général, j'écris des commentaires de la manière suggérée par La gueule d'une vache . J'écris aussi toujours des commentaires générant de la documentation (Doxygen, JavaDoc) de cette manière.

Cependant, nombreux sont ceux qui négligent souvent l'utilisation du contrôle de version pour identifier qui a écrit / touché les lignes dans les fichiers source. Parfois, il est approprié de dire "Je", en particulier lorsqu'il est assez facile de retracer le "Je" à la personne qui a écrit le code. Si vous, en tant qu'individu, avez pris une décision, je vous recommande d'utiliser "I" (avec le contrôle de version) pour identifier et suivre les décisions conformément au code.


+1 pour Doxygen et JavaDoc. Je conviens que la documentation est distincte des commentaires (même si certains génèrent de la documentation) et je fais de mon mieux pour que cette documentation reste une étape plus formelle que mes commentaires.
dlras2

1

Mon bon vieux père (mhrip) me demandait: "N'as-tu pas des choses plus importantes à se soucier?"

Cependant, personnellement, j'aime bien le "nous". Et je me demande aussi pourquoi je vous écris dans des documents en amont, pas même du code, étant donné que je suis le seul employé de mon entreprise.

Cependant, moi-même et moi-même sommes d'accord pour dire que nous nous sentons ainsi moins seuls :)


1

Suis-je le seul à écrire "nous" et à penser "moi et l'ordinateur" (ou "mon équipe et l'ordinateur")? "Nous" allons traiter la demande que l'extérieur nous a donnée, ce qui signifie "nous" devons lire la demande, ouvrir des fenêtres, faire des calculs, en fonction de "nos" besoins opérationnels. Cela aide également à voir le code comme une partie de votre côté, pas comme un ennemi :-)


0

Pour de brefs commentaires, j'écris parfois à la deuxième personne, comme si je demandais à quelqu'un d'autre, presque comme un message dirigé au prochain développeur pour lire le commentaire. Tel que

//You can get a session_id from SYSSession.getSessionID() if you need one

Commentaires plus longs (tels qu'un en-tête de fonction long ou plusieurs lignes de description d'algorithme) J'essaie de rester neutre, pas à la première personne, à la deuxième ou à la troisième personne.


Anglais passif sonne rarement bien: "Un session_id peut être obtenu à partir de SYSSession.getSessionID () si on en a besoin"
jkj

0

Vous avez ajouté ce commentaire parce que le code n'était pas assez clair. Je trouve généralement que l'expression de l'intention par des méthodes bien définies évite l'utilisation de commentaires. Par exemple, cette ligne aurait pu être déplacée vers une méthode nommée CanThisFormBeResized.

Une méthode bien nommée, aussi petite soit-elle, bat un commentaire, car il est facile de désynchroniser les commentaires et le code.

Donc, si la plupart des commentaires peuvent être exprimés en code, cela ne laisse que très peu de raisons de les commenter.

  • Si votre commentaire est votre opinion, commencez par "I"
  • Si vous pensez que votre commentaire doit être une opinion partagée (par exemple, une meilleure pratique), commencez par "nous"
  • Si votre commentaire s'adresse à un code douteux écrit par un demi-esprit, alors supprimez-le, approchez-vous et frappez-le avec un code confus d'un collègue, puis adressez-le en face à face.

1
Désolé, mais je ne suis pas vraiment fan de ce style. D'autant que ce code est utilisé une fois, à un endroit et qu'il est déjà la seule chose dans la méthode de redimensionnement. Je préférerais un commentaire court et bien rédigé à une complexité accrue par le refactoring, en particulier lorsque vous utilisez le débogueur VB6. En passant , CanThisFormBeResizeddevrait probablement être ThisFormCanBeResizedsi il va être utilisé comme If ThisFormCanBeResized Then.
dlras2

1
C'est la préférence. Je prends une méthode booléenne privée comme function() { return this.windowState != 1 }sur tout commentaire. +1 de moi
keppla

1
@ Dan, que se passe-t-il si quelqu'un d'autre vient plus tard: pourquoi leur demander de chercher et de revoir la logique pour déterminer si une fenêtre peut être minimisée? Ils pourraient même ne pas repérer votre petite ligne de code avec un commentaire et ajouter le leur. Vous avez maintenant deux endroits à modifier en cas de changement de logique et deux endroits où les commentaires risquent de ne plus être synchronisés avec le code. Pourquoi une méthode bien nommée sur une ligne (qui ne change pas d'état) ajoute-t-elle à la complexité? C'est la refonte la plus simple et la plus propre qui soit.
Steve Dunn

0

En règle générale, je suggère d'utiliser la première personne, c'est-à-dire I.

Pourquoi? Pas à cause de la nature possessive de moi, mais parce que lorsque les gens parlent dans une autre perspective, ils ont tendance à utiliser trop de mots ou à rendre des phrases trop complexes, et à se perdre en essayant d'expliquer les choses. La première personne a toujours tendance à être plus facile à lire.


0

Personnellement j'écrirais (en C #):

if (WindowState != WindowState.Minimised)
{
     ResizeWindowSafely();
}

Ou quelque chose du genre, ne nécessitant donc pas de commentaires.


ResizeWindowSafelycela impliquerait qu'il peut être appelé si vous ne savez pas s'il faut redimensionner ou non, et aurait donc besoin de l'inclure if (WindowState != WindowState.Minimised)lui - même.
dlras2
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.