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

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?

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».

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.

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".

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.

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)

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).

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.

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.

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.

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.

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 :)

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 :-)

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.

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.

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.

Personnellement j'écrirais (en C #):

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

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