Existe-t-il une excuse pour les noms de variables courts?

Cela est devenu une grande frustration avec le code sur lequel je travaille actuellement; beaucoup de nos noms de variables sont courts et non descriptifs. Je suis le seul développeur qui reste sur le projet et il n'y a pas de documentation sur ce que font la plupart d'entre eux. Je dois donc passer plus de temps à rechercher ce qu'ils représentent.

Par exemple, je lisais un code qui met à jour la définition d’une surface optique. Les variables définies au début étaient les suivantes:

double dR, dCV, dK, dDin, dDout, dRin, dRout
dR = Convert.ToDouble(_tblAsphere.Rows[0].ItemArray.GetValue(1));
dCV = convert.ToDouble(_tblAsphere.Rows[1].ItemArray.GetValue(1));
... and so on

Peut-être que c'est juste moi, mais cela ne me dit essentiellement rien de ce qu'ils représentaient, ce qui rendait la compréhension du code plus difficile. Tout ce que je savais, c'est qu'il s'agissait d'une variable analysée dans une ligne spécifique d'une table spécifique, quelque part. Après quelques recherches, j'ai découvert ce qu'ils voulaient dire:

dR = radius
dCV = curvature
dK = conic constant
dDin = inner aperture
dDout = outer aperture
dRin = inner radius
dRout = outer radius

Je les ai renommés pour essentiellement ce que j'ai là-haut. Cela rallonge certaines lignes, mais j'estime que c'est un compromis équitable. Ce type de schéma de nommage est toutefois utilisé dans une grande partie du code. Je ne sais pas si c'est un artefact de développeurs qui ont appris à travailler avec des systèmes plus anciens, ou s'il y a une raison plus profonde derrière cela. Existe-t-il une bonne raison de nommer les variables de cette façon ou ai-je le droit de les mettre à jour avec des noms plus descriptifs au fur et à mesure que je les rencontre?

Il semble que ces noms de variables soient basés sur les abréviations que vous vous attendriez à trouver dans un manuel de physique traitant de divers problèmes d’optique. C'est l'une des situations où les noms de variables courts sont souvent préférables aux noms de variables plus longs. Si vous avez des physiciens (ou des personnes habituées à résoudre manuellement les équations) qui sont habitués à utiliser des abréviations courantes telles que Rin, Rout, etc., le code sera beaucoup plus clair avec ces abréviations qu'avec des noms de variable plus longs. Il est également beaucoup plus facile de comparer les formules d’articles et de manuels avec du code afin de s’assurer que le code effectue correctement les calculs.

Toute personne familiarisée avec l'optique reconnaîtra immédiatement quelque chose comme Rin en tant que rayon intérieur (dans un article de physique, il inserait rendu en indice), Rout en tant que rayon extérieur, etc. Bien qu'ils seraient presque certainement en mesure de traduire mentalement quelque chose comme innerRadiuspour la nomenclature plus familière, cela rendrait le code moins clair pour cette personne. Il serait plus difficile de repérer les cas où une formule familière avait été mal codée et il serait plus difficile de traduire les équations en code en utilisant les équations qu’ils trouveraient dans un document ou un manuel.

Si vous êtes la seule personne à consulter ce code, vous n'avez jamais besoin de faire la distinction entre le code et une équation d'optique standard. Il est peu probable qu'un physicien doive consulter le code à l'avenir. logique de refactoriser, car le bénéfice des abréviations ne dépasse plus le coût. S'il s'agissait d'un nouveau développement, il serait certainement logique d'utiliser les mêmes abréviations dans le code que celles que vous trouverez dans la littérature.

Les variables ayant une courte durée de vie devraient être nommées sous peu. Par exemple, vous n'écrivez pas for(int arrayCounter = 0; arrayCounter < 10; arrayCounter++) { .... Au lieu de cela, vous utilisez for(int i ....

En règle générale, on pourrait dire que plus la portée de la variable est courte, plus le nom doit être court. Compteurs de boucle ne sont souvent que de simples lettres, disent i, jet k. Les variables locales sont quelque chose comme baseou fromet to. Les variables globales sont alors un peu plus élaborées, par exemple EntityTablePointer.

Peut-être qu'une règle comme celle-ci n'est pas suivie par la base de code avec laquelle vous travaillez. C'est une bonne raison de faire du refactoring!

Le problème avec le code n’est pas les noms abrégés, mais plutôt l’absence de commentaire qui expliquerait les abréviations ou indiquerait des informations utiles sur les formules à partir desquelles les variables sont dérivées.

Le code suppose simplement la familiarité du domaine du problème.

C'est bien, car la connaissance du domaine problématique est probablement nécessaire pour comprendre et conserver le code, en particulier dans le rôle de "propriétaire", de sorte qu'il vous incombe d'acquérir cette familiarité plutôt que d'allonger les noms.

Mais ce serait bien si le code fournissait quelques astuces pour servir de tremplin. Même un expert de domaine pourrait oublier que dKc'est une constante de conique. Ajouter un petit "aide-mémoire" dans un bloc de commentaires ne ferait pas de mal.

Pour certaines variables bien connues dans le domaine du problème - comme dans le cas présent - les noms de variables abrégés sont raisonnables. Si je travaille sur un jeu, je veux que mes entités de jeu pour avoir des variables de position xet y, non horizontalPositionet verticalPosition. De même , les compteurs de boucles qui n'ont pas de sémantique au - delà de l' indexation, je voir i, j, k.

Selon "Code propre":

Les noms de variables doivent:

• Être l'intention révélant
• Éviter la désinformation
• Faire des distinctions significatives
• Être prononçable
• Être consultable

Les exceptions sont les proverbiales i,j,k,m,nutilisées dans les boucles for.

La variable vous nomme, à juste titre, vous plaindre de ne rien faire de ce qui précède. Ces noms sont des mauvais noms.

De plus, comme chaque méthode doit être courte , l'utilisation de préfixes pour indiquer que la portée ou le type n'est plus utilisée.

Ces noms sont meilleurs:

radius
curvature
conicConstant
innerAperture
outerAperture
innerRadius
outerRadius

Un commentateur dit que cela serait trop complexe avec de longs noms de variables:

Les noms de variables courts ne rendent pas les choses simples non plus:

fnZR = (r^2/fnR(1+Math.sqrt((1+k) * (r^2/R^2)))) + a[1]*r^2 + a[1]*r^4 + a[1]*r^6 ...;

La réponse est des noms longs et des résultats intermédiaires jusqu'à ce que vous obteniez ceci à la fin:

thisNiceThing =  ( thisOKThing / thisGreatThing ) + thisAwsomeThing;

Il y a deux bonnes raisons de ne pas renommer les variables dans le code hérité.

(1) sauf si vous utilisez un outil de refactoring automatisé, la possibilité d'introduire des bogues est élevée. Par conséquent, "si ce n'est pas cassé, ne le corrige pas"

(2) vous ferez la comparaison des versions actuelles avec les versions antérieures, afin de voir ce qui a changé, impossible. Cela rendra plus difficile la maintenance future du code.

Existe-t-il une bonne raison de nommer les variables de cette façon ou ai-je le droit de les mettre à jour avec des noms plus descriptifs au fur et à mesure que je les rencontre?

La raison d'utiliser des noms plus petits est si le programmeur d'origine les trouve plus faciles à utiliser. Ils ont vraisemblablement le droit de constater que tel est le cas et le droit de ne pas avoir les mêmes préférences personnelles que vous. Personnellement, je trouverais ...

dDin better than dDinnerAperture
dDout better than dDouterAperture

... si je les utilisais dans des calculs longs et complexes. Plus l'expression mathématique est petite, plus il est facile de voir le tout en une fois. Bien que si c'était le cas, ils pourraient être meilleurs en tant que dIn et dOut, donc il n'y avait pas un D répétitif qui pourrait conduire à une faute de frappe facile.

D'un autre côté, si vous avez du mal à travailler avec, assommez-vous et renommez ensuite leur forme plus longue. Surtout si vous êtes responsable de ce code.

En règle générale, j'estime que la règle à cet égard devrait être que vous pouvez utiliser des noms de variable extrêmement courts, car vous savez que les personnes "expérimentées dans l'art" de votre code comprendront immédiatement la référence de ce nom de variable. (Vous avez toujours des commentaires à l'exception de ce cas de toute façon), et que l'utilisation localisée des variables peut facilement être discernée en fonction du contexte de leur utilisation.

Pour en savoir plus, cela signifie que vous ne devriez pas faire tout votre possible pour dissimuler les noms de vos variables, mais vous pouvez utiliser des abréviations pour les noms de vos variables, sachant que seules les personnes qui comprennent le concept sous-jacent de votre code sont susceptibles. de le lire quand même.

Pour utiliser un exemple concret, récemment, je créais une classe Javascript qui prenait une latitude et vous indiquait la quantité de lumière solaire attendue à une date donnée.

Pour créer cette classe de cadran solaire , j'ai fait référence à une demi-douzaine de ressources, à l'almanach d'astronomie et à des extraits d'autres langages (PHP, Java, C, etc.).

Dans presque tous ces cas, ils utilisaient des abréviations identiques, ce qui, à première vue, ne signifie absolument rien.

K, T, EPS, deltaPsi, eot, LM,RA

Cependant, si vous avez des connaissances en physique, vous pouvez comprendre ce qu’elles étaient. Je ne m'attendrais pas à ce que quelqu'un d'autre touche à ce code, alors pourquoi utiliser des noms de variables verbeux?

julianTime, nutationOfEclipticalLongitudeExpressedInDegrees, equationOfTime, longitudeMean, rightAscension.

En outre, la plupart du temps, lorsque les noms de variable sont transitoires, c’est-à-dire qu’ils ne sont utilisés que pour allouer temporairement une valeur, il n’est souvent pas utile d’utiliser une version verbeuse, en particulier lorsque le contexte de la variable explique son but.

Il y a absolument; souvent, un nom de variable court est tout ce qui est nécessaire.

Dans mon cas, je fais de la navigation par points de cheminement dans mon cours de robotique, et nous programmons nos robots dans KISS-C. Nous avons besoin de variables pour les coordonnées actuelles et de destination (x, y), les distances (x, y), les en-têtes de courant et de destination, ainsi que les angles de virage.

Surtout dans le cas des coordonnées x et y, un nom de variable long est complètement inutile, et des noms tels que xC (x actuel), yD (destination y) et pD (destination phi) suffisent et sont les plus faciles à comprendre. dans ce cas.

Vous pouvez faire valoir que ce ne sont pas des "noms de variables descriptifs" comme le dicte le protocole du programmeur, mais puisque les noms sont basés sur un code simple (d = destination, c = actuel), un commentaire très simple au départ est toute la description. Ils demandent.

Existe-t-il une bonne raison de nommer les variables de cette façon ou ai-je le droit de les mettre à jour avec des noms plus descriptifs au fur et à mesure que je les rencontre?

Habituellement, des algorithmes complexes sont implémentés dans matlab (ou un langage similaire). Ce que j'ai vu, ce sont des personnes qui prennent juste le nom des variables. De cette façon, il est simple de comparer les implémentations.

Toutes les autres réponses sont presque correctes. Ces abréviations peuvent être trouvées en mathématiques et en physique, sauf qu'elles ne commencent pas par d(comme dans votre exemple). Les variables commençant par d sont généralement nommées pour représenter la différenciation .

Tous les guides de codage normaux disent de ne pas nommer les variables avec la première lettre représentant le type (comme dans votre cas), car il est très facile de parcourir le code dans tous les IDE modernes.

Je peux penser à une raison pour laquelle les noms de variable sont raisonnablement courts.

Les noms abrégés sont faciles à lire en utilisant une portée visuelle plus courte, d’où une courte durée d’attention.

Par exemple, une fois que je me suis habitué au fait que svdb signifie "enregistrer dans la base de données", la vitesse d'analyse du code source s'améliore car je n'ai qu'à analyser rapidement 4 caractères au lieu de lire SaveToDatabase (14 caractères, la situation empire pour les noms d’opérations plus complexes). Je dis "scanner" pas "lire", car cela prend une part importante de l'analyse du code source.

Lorsque vous parcourez une grande quantité de code source, cela peut générer de bons gains de performances.

En outre, cela aide simplement le programmeur paresseux à taper ces noms abrégés lors de l'écriture de code.

Bien entendu, tous ces "raccourcis" devraient figurer dans un emplacement standard du code source.

Pour formuler ce que @zxcdw a dit d’une manière légèrement différente, et en préciser l’approche:

Les fonctions doivent être pures , brèves et constituer une encapsulation parfaite de certaines fonctionnalités: la logique de la boîte noire , qu'elle soit ou non restée inchangée depuis 40 ans, continuera à faire le travail pour lequel elle a été conçue, car son interface (entrée et sortie) est sain, même si vous ne savez rien de ses internes.

C’est le genre de code que vous voulez écrire: c’est du code qui dure et qui est simple à porter.

Si nécessaire, composez des fonctions à partir d' autres appels de fonctions (en ligne) , afin que le code soit affiné.

Désormais, avec un nom de fonction suffisamment descriptif (détaillé si nécessaire!), Nous minimisons les risques d'interprétation erronée de ces noms de variables abrégés, car la portée est si petite.

Les noms de variables doivent être aussi descriptifs que possible pour améliorer la lisibilité du programme. Vous l'avez vécu vous-même: vous avez eu beaucoup de mal à identifier ce que le programme a fait à cause de la mauvaise désignation.

Il n'y a aucune bonne raison de ne pas utiliser un nom descriptif. Cela vous aidera, et tous les autres qui travaillent / travailleront sur le projet. En fait, il n’ya qu’une seule utilisation valide pour les noms abrégés: les compteurs de boucles.

C'est sûrement à quoi // les commentaires servent?

Si les affectations ont des commentaires descriptifs, vous obtenez le meilleur des deux mondes: une description de la variable et des équations sont facilement comparables avec leur équivalent du manuel.

Pour les interfaces (par exemple, signatures de méthode, signatures de fonction), j'ai tendance à résoudre ce problème en annotant les déclarations de paramètres. Pour C / C ++, cela décore le fichier .h ainsi que le code de l’implémentation.

Je fais la même chose pour les déclarations de variables où connaître l’utilisation de la variable n’est pas évident dans le contexte et dans le nommage. (Ceci s’applique également dans les langues qui ne sont pas fortement dactylographiées.)

Il y a beaucoup de choses que nous ne voulons pas obstruer le nom de la variable. L'angle est-il en radians ou en degrés, existe-t-il une tolérance de précision ou de plage, etc. L'information peut fournir des assertions précieuses sur les caractéristiques qui doivent être traitées correctement.

Je ne suis pas religieux à ce sujet. Je suis simplement intéressé par la clarté et par le fait de veiller à ce que c’est la prochaine fois que mon oubli me rend visite au code. Et quiconque regarde par-dessus mon épaule a ce qu’il a besoin de savoir pour voir où quelque chose ne va pas, ce qui est essentiel (le dernier élément essentiel pour un entretien correct).

Existe-t-il une excuse pour des noms de variable excessivement courts?

Premièrement: Nommer une variable pour l'énergie e lors du calcul de formules telles que E = MC2 n'est PAS une dénomination excessivement courte. L'utilisation de symboles comme argument pour les noms abrégés n'est pas valide

Cette question était plutôt intéressante pour moi et je ne peux penser qu’à une seule excuse: c’est l’argent.

Supposons, par exemple, que vous connectez du code javascript à un client qui sait que le fichier doit être téléchargé plusieurs fois par seconde. Cela coûterait moins cher et améliorerait l'expérience des utilisateurs si le fichier (en nombre d'octets) est aussi petit que possible.

(Juste pour garder l'exemple "réaliste", vous n'étiez pas autorisé à utiliser un outil de minification, pourquoi? Problèmes de sécurité, aucun outil externe autorisé à toucher au code de base.)

Je remarque que les autres réponses ne mentionnent pas l'utilisation de la notation hongroise. Ceci est orthogonal au débat sur la longueur, mais concerne les systèmes de nommage en général.

double dR, dCV, dK, dDin, dDout, dRin, dRout

Le "d" au début de toutes ces variables est censé indiquer qu'elles sont doubles; mais le langage l'applique quand même. Malgré la rareté de ces noms, ils sont jusqu'à 50% redondants !

Si nous allons utiliser une convention de dénomination pour réduire les erreurs, nous ferons bien mieux d'encoder des informations qui ne sont pas vérifiées par la langue. Par exemple, aucune langue ne se plaindra dK + dRdans le code ci-dessus, même si cela n'a pas de sens d'ajouter un nombre sans dimension à une longueur.

Un bon moyen d'éviter de telles erreurs consiste à utiliser des types plus puissants. Cependant, si nous utilisons des doublons, un schéma de nommage plus approprié pourrait être:

// Dimensions:
// l  = length
// rl = reciprocal length
double lR, rlCV, K, lDin, lDout, lRin, lRout

Le langage nous permettra toujours d’écrire K + lR, mais à présent, les noms nous donnent à penser que cela pourrait être incorrect.

C'est la différence entre les systèmes Hungarian (généralement mauvais) et Apps Hungarian (éventuellement bon)

http://en.wikipedia.org/wiki/Hungarian_notation

Le seul cas où des noms de variable courts illisibles sont acceptables dans le génie logiciel moderne est lorsqu'ils existent dans un script et que le débit de ce script (sur un réseau en général) est important. Même dans ce cas, conservez le script avec des noms longs dans le contrôle de source et réduisez- le en production.