Existe-t-il une excuse pour les noms de variables courts?
Cela est devenu une grande frustration avec la base de code dans laquelle 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 la plupart d'entre eux font, donc je dois passer plus de temps à traquer ce qu'ils représentent.
Par exemple, je lisais du code qui met à jour la définition d'une surface optique. Les variables définies au départ é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 m'a rien dit sur ce qu'ils représentaient, ce qui a rendu la compréhension du code plus difficile. Tout ce que je savais, c'était qu'il s'agissait d'une variable analysant une ligne spécifique d'une table spécifique, quelque part. Après quelques recherches, j'ai découvert ce qu'ils signifiaient:
dR = radius
dCV = curvature
dK = conic constant
dDin = inner aperture
dDout = outer aperture
dRin = inner radius
dRout = outer radius
Je les ai renommés essentiellement en ce que j'ai là-haut. Cela allonge certaines lignes, mais j'ai l'impression que c'est un compromis équitable. Ce type de schéma de dénomination est cependant utilisé dans une grande partie du code. Je ne sais pas si c'est un artefact de développeurs qui ont appris en travaillant avec des systèmes plus anciens, ou s'il y a une raison plus profonde derrière cela. Y a-t-il une bonne raison de nommer les variables de cette façon, ou suis-je justifié de les mettre à jour vers 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 attendez à trouver dans un manuel de physique travaillant sur 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 à travailler les équations à la main) qui sont habituées à utiliser des abréviations courantes comme Rin, Rout, etc., le code sera beaucoup plus clair avec ces abréviations qu'avec des noms de variables plus longs. Cela permet également de comparer beaucoup plus facilement les formules des articles et des manuels avec le code pour vous assurer que le code effectue correctement les calculs.
Quiconque est familier avec l'optique reconnaîtra immédiatement quelque chose comme Rin comme le rayon intérieur (dans un article de physique, le in serait rendu en indice), Rout comme le rayon extérieur, etc. Bien qu'ils le feraient presque certainement être capable de traduire mentalement quelque chose comme innerRadius dans 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é incorrectement codée et il serait plus difficile de traduire des équations en code vers et depuis les équations qu'ils trouveraient dans un document ou un manuel.
Si vous êtes la seule personne à avoir regardé ce code, vous n'avez jamais besoin de faire la traduction entre le code et une équation optique standard, et il est peu probable qu'un physicien ait besoin de regarder le code à l'avenir, peut-être qu'il le fera Il est logique de refactoriser car l'avantage des abréviations ne l'emporte plus sur le coût. S'il s'agissait d'un nouveau développement, cependant, il serait presque certainement judicieux d'utiliser les mêmes abréviations dans le code que vous trouveriez dans la littérature.
Les variables à courte durée de vie doivent être nommées sous peu. Par exemple, vous n'écrivez pas for(int arrayCounter = 0; arrayCounter < 10; arrayCounter++) { .... À la place, 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. Les compteurs de boucles ne sont souvent que des lettres simples, par exemple i, j et k. Les variables locales sont quelque chose comme base ou from et 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 avec la base de code avec laquelle vous travaillez. C'est une bonne raison pour 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 éléments utiles sur les formules à partir desquelles les variables sont dérivées.
Le code suppose simplement la familiarité du domaine de problème.
C'est très bien, car la familiarité avec le domaine du problème est probablement nécessaire pour comprendre et maintenir le code, en particulier dans le rôle de quelqu'un qui le "possède", il vous incombe donc d'acquérir la familiarité plutôt que d'aller plus loin en allongeant les noms.
Mais ce serait bien si le code fournissait quelques indices pour servir de tremplin. Même un expert en domaine pourrait oublier que dK est une constante conique. Ajouter une petite "feuille de triche" dans un bloc de commentaires ne ferait pas de mal.
Pour certaines variables qui sont bien connues dans le domaine problématique - comme le cas que vous avez ici - les noms de variables laconiques sont raisonnables. Si je travaille sur un jeu, je veux que mes entités de jeu aient des variables de position x et y, pas horizontalPosition et verticalPosition. De même, les compteurs de boucles qui n'ont pas de sémantique au-delà de l'indexation, je m'attends à voir i, j, k.
Selon "Clean Code":
Les noms de variables doivent:
- Soyez révélateur d'intention
- Évitez la désinformation
- Faites des distinctions significatives
- Soyez prononçable
- Soyez consultable
Les exceptions sont les proverbiales i,j,k,m,n utilisé dans les boucles for.
Les noms de variables dont vous vous plaignez, à juste titre, ne font rien de ce qui précède. Ces noms sont de mauvais noms.
Aussi, comme chaque méthode doit être courte, en utilisant des préfixes pour indiquer que la portée ou le type n'est plus utilisé.
Ces noms sont meilleurs:
radius
curvature
conicConstant
innerAperture
outerAperture
innerRadius
outerRadius
Un commentateur dit que ce serait trop complexe avec de longs noms de variables:
Les noms de variables courts ne le rendent pas simple 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) à moins que vous n'utilisiez un outil de refactorisation automatisé, la possibilité d'introduire des bogues est élevée. Par conséquent, "s'il n'est pas cassé, ne le réparez pas"
(2) vous ferez la comparaison des versions actuelles avec les versions antérieures, afin de voir ce qui a changé, impossible. Cela rendra la maintenance future du code plus difficile.
Y a-t-il une bonne raison de nommer les variables de cette façon, ou ai-je raison de les mettre à jour vers des noms plus descriptifs lorsque je les rencontre?
La raison d'utiliser des noms plus petits est que le programmeur d'origine les trouve plus faciles à utiliser. Vraisemblablement, ils ont le droit de constater que c'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, souvent plus il est facile de voir le tout à la fois. Si tel était le cas, ils pourraient être meilleurs en tant que dIn et dOut, donc il n'y avait pas de D répétitif qui pourrait conduire à une faute de frappe facile.
D'un autre côté, si vous trouvez plus difficile de travailler avec, alors assommez-vous et renommez-le ensuite sous sa forme plus longue. Surtout si vous êtes responsable de ce code.
En règle générale, je crois que la règle à cet égard devrait être que vous pouvez utiliser des noms de variable extrêmement courts lorsque vous savez que les personnes "qualifiées" de votre code particulier 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 développer cela, cela signifie que vous ne devriez pas faire tout votre possible pour obscurcir vos noms de variables, mais vous pouvez utiliser des abréviations pour les noms de vos variables, où vous savez 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 du monde réel, récemment, je créais un classe Javascript qui prendrait une latitude et vous indiquerait la quantité de lumière du soleil que vous attendez à une date donnée.
Pour créer ceci classe Sundial , j'ai fait référence à peut-être 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 ont utilisé des abréviations identiques et similaires, qui à première vue ne signifient rien d'absolu.
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 détaillés?
julianTime, nutationOfEclipticalLongitudeExpressedInDegrees, equationOfTime, longitudeMean, rightAscension.
De plus, la plupart du temps, lorsque les noms de variables sont transitoires, c'est-à-dire qu'ils ne sont utilisés que pour allouer temporairement une certaine valeur, il est souvent inutile d'utiliser une version détaillée, en particulier lorsque le contexte de la variable explique son but.
Il y en a absolument; souvent, un court nom de variable suffit.
Dans mon cas, je fais de la navigation par waypoint dans ma classe de robotique senior, et nous programmons nos robots en KISS-C. Nous avons besoin de variables pour les coordonnées actuelles et de destination (x, y), les distances (x, y), les caps actuels et de destination, ainsi que les angles de virage.
En particulier 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 pourriez faire valoir que ce ne sont pas des "noms de variables descriptives" comme le dicterait le protocole du programmeur, mais comme les noms sont basés sur un code simple (d = destination, c = courant), un commentaire très simple au départ est toute la description Ils demandent.
Y a-t-il une bonne raison de nommer les variables de cette façon, ou ai-je raison de les mettre à jour vers des noms plus descriptifs lorsque je les rencontre?
Habituellement, des algorithmes complexes sont implémentés dans matlab (ou un langage similaire). Ce que j'ai vu, c'est que les gens prennent simplement 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 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 si facile de parcourir le code dans tous les IDE modernes.
Je peux penser à une raison pour que les noms de variables soient raisonnablement courts.
Les noms courts sont faciles à lire en utilisant une portée oculaire 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", le taux d'analyse du code source s'améliore car je n'ai qu'à scanner rapidement 4 caractères au lieu de lire SaveToDatabase (14 caractères, les choses empirent pour les noms d'opérations plus complexes). Je dis "numérisation" et non "lecture", car cela prend une grande partie de l'analyse du code source.
Lorsque vous parcourez une grande quantité de code source, cela peut fournir de bons gains de performances.
En outre, cela aide simplement le programmeur paresseux à taper ces noms courts lors de l'écriture de code.
Bien sûr, tous ces "raccourcis" devraient être répertoriés dans un emplacement standard du code source.
Pour encadrer ce que @zxcdw a dit d'une manière légèrement différente, et élaborer en termes d'approche:
Les fonctions doivent être pure, brèves et une parfaite encapsulation de certaines fonctionnalités: logique de la boîte noire , indépendamment du fait qu'elle soit restée intacte pendant 40 ans, elle continuera à faites le travail pour lequel il a été conçu, car son interface (entrée et sortie) est solide, même si vous ne savez rien de ses composants internes.
C'est le type de code que vous voulez écrire: c'est du code qui dure et qui est simple à porter.
Si nécessaire, composez des fonctions à partir de autre (en ligne) appels de fonction , pour garder le code affiné.
Maintenant, avec un nom de fonction convenablement descriptif (verbeux si nécessaire!), Nous minimisons tout risque d'interprétation erronée de ces noms de variable raccourcis, car la portée est si petite.