À quel point le code peut-il être «auto-documenté» sans être ennuyeux? [fermé]

Question

Je ne sais pas quelles sont les meilleures pratiques, mais je vois souvent des noms de variables abrégés, en particulier lorsque la portée est petite. Donc (pour utiliser des exemples Ruby simples) au lieu de def add_location (nom, coordonnées) , je vois des choses comme def add_loc (nom, coord) & # 8212; et je pourrais même voir quelque chose comme def add_loc (n, x, y) . J'imagine que des noms longs peuvent fatiguer une personne lorsqu'elle est habituée à voir les abréviations.

La verbosité améliore-t-elle la lisibilité ou ne fait-elle que faire mal aux yeux de tout le monde? Les personnes préfèrent-elles les abréviations et les noms abrégés aux noms longs?

Answer 1

Personnellement, je préférerais BEAUCOUP voir plutôt des noms plus longs qui signifient réellement quelque chose sans avoir à déterminer le contexte au préalable. Bien sûr, les variables qui ne donnent pas de véritable sens, comme les compteurs, j’utilise toujours de petits noms de variables sans signification (tels que i ou x ), mais sinon la verbosité est la clarté la plupart du temps. Cela est particulièrement vrai avec les API publiques.

Cela peut toutefois être poussé trop loin. J'ai déjà vu un code VB ridicule. La modération comme tout le reste!

Answer 2

J'utilise en fait de longs noms de variable tout le temps, une fois que tous les IDE modernes et les outils de traitement de texte sont terminés. Il n'y a donc rien de mal à utiliser index à la place si i. La seule exception que je connaisse concerne les coordonnées b / c x et y , qui ont le plus de sens ici.

Answer 3

Ne jamais abbr.

Answer 4

Le nom le plus court possible doit être attribué à une variable, qui en indique le but.

La verbosité excessive tend à dissimuler la syntaxe, laquelle est importante.

Sur l’ensemble du programme (ou de l’application / système), les variables doivent être nommées avec un style cohérent et les éléments similaires doivent être nommés de la même manière. Si une convention existe au sein de la communauté linguistique, il convient de la respecter (à condition de ne pas camelCaseRubyVariableNames), à moins d’une raison impérieuse de ne pas le faire.

Les abréviations, si elles sont utilisées, doivent être systématiquement appliquées partout et, si elles sont spécifiques à un domaine, doivent être enregistrées quelque part. Si quelqu'un passe assez de temps avec le code, il apprendra bientôt.

Si vous avez besoin de combiner jusqu'à cinq ou six mots pour nommer une variable, nous vous suggérons de regarder un odeur de code et la routine que vous travaillez peut bénéficier d'un peu de travail.

Toutefois, si vous êtes au courant des pièges et que vous pensez à ce que vous écrivez, il y a de fortes chances que votre code soit raisonnable. Imaginez-vous en train de décrire la fonction sur laquelle vous travaillez à un nouveau collègue - moins vous pensez avoir besoin de le dire, meilleur est le code.

Answer 5

Essayez de lire votre propre code un an plus tard. Vous verrez à la fois la valeur des noms de variables auto-documentés et la valeur des commentaires de code (et spécialement la valeur du code vierge)

Lorsque vous prenez le code source de quelqu'un d'autre sans le comprendre, il est facile de penser: "Il n'est pas aussi bon programmeur que moi". Mais quand vous réalisez que votre propre code est difficile à lire, vous vous dites: "à quoi pensais-je?"

À long terme, la verbosité facilite la maintenabilité. Pour un script court d’une ligne, vous pouvez toujours utiliser " setLocNm " au lieu de setLocationName "

Tout imbécile peut écrire du code qu'un ordinateur peut comprendre. Les bons programmeurs écrivent un code que les humains peuvent comprendre. - Martin Fowler

Answer 6

Personnellement, je trouve que la verbosité est une bonne chose, mais il est facile d’être trop verbeuse aussi, ce qui est une mauvaise chose. Il existe un équilibre et les abréviations peuvent également entrer dans cet équilibre.

Ce sont mes règles générales:

• Les itérateurs peuvent être une lettre, c'est-à-dire. i , j , k , etc.
• D'autres variables d'un seul mot, telles que boolean, permettent de ne pas être abrégé, c'est-à-dire. installation , terminé , etc.
• Plusieurs variables de mots et noms de fonctions sont candidats à l’abréviation, mais seulement s’ils commencent à devenir très longs (par exemple, 20-25 caractères ou plus). L'abréviation intelligente est la clé ici. function = > func par exemple, mais jamais fun , f ou functi

Answer 7

J'ai parcouru les réponses, mais je ne vois pas si ce qui suit est couvert. Ça y est ...

Que vous abrégiez ou que vous soyez verbeux, assurez-vous de ne pas utiliser plus de mots que nécessaire et que le sens est parfaitement évident.

Mais même après ce filtrage si vos identifiants ont l'air verbeux, vous avez un défaut dans votre conception.

def initialize_report_template()
end

aurait dû être ...

class ReportTemplate
    def initialize()
    end
end

Answer 8

Les noms longs sont bien meilleurs. Vous mentionnez que vous voyez souvent des noms abrégés dans de petites zones. Qui peut dire que la portée restera petite au fur et à mesure que le logiciel grandira?

Bien sûr, XCoordinateForCurrentLocationOfSelf est un nom ridicule, soyez donc raisonnable. Surtout si vous vous lancez dans un projet sur lequel vous n'avez pas encore travaillé, vous remercierez tous ceux qui utilisent des fonctions descriptives et des noms de variables.

Answer 9

Je pense qu'il est correct d'abréger le nom lorsque celui-ci nuit à la lisibilité ou est simplement redondant.

Exemple 1: argument d'une méthode dont le type véhicule déjà toutes les informations nécessaires.

Exemple 2: une variable qui utilisera beaucoup de manière évidente

StringBuilder sb = ...
sb.append(...
sb.append(...
return sb.toString();

Exemple 3: Abréviations idiomatiques. i, j, k a déjà été mentionné. " sb " ci-dessus est un dans notre code, et chaque équipe a probablement un couple de plus.

Answer 10

Prévoyez une durée plus courte que longue, mais la compréhension du lecteur devrait l'emporter sur la paresse de taper à chaque fois.

Comme d'autres l'ont dit, la longueur du nom de variable ne doit pas masquer la logique ou l'algorithme. Par exemple, en arithmétique, nous écrivons

( 1 + 5 ) * 3 = 18

plutôt que

three multiplied by the sum of one and five equals eighteen

parce que nous essayons d'attirer l'attention sur autre chose que la clarté des éléments impliqués dans l'expression.

J'ai tendance à garder les variables de un à trois mots, en n’abréviant que lorsque j’ai plus de 24 caractères. Moins une variable est utilisée fréquemment, plus je suis libre de donner un nom long à la variable. Les variables les plus fréquemment utilisées seront raccourcies.

Answer 11

Max Kanat-Alexander, l'architecte en chef de Bugzilla, a déclaré ceci sur son blog:

  

Le code lui-même devrait occuper un espace proportionnel à sa signification.

     

Fondamentalement, de minuscules symboles qui signifient un   beaucoup rendent le code difficile à lire. Très long   Les noms qui ne veulent pas dire grand chose font aussi   code difficile à lire. La quantité de   le sens et l'espace occupé devrait   être étroitement liés les uns aux autres.

http://www.codesimplicity.com/post/readability-and -naming-things /

C’est un article très perspicace sur la nomination de noms. J'exhorte tout le monde à le lire!

Answer 12

Le seul moment où j'accepte les abréviations concerne les variables locales dont la portée ne dure que peu de temps.

Cela signifie qu'ils devraient entrer dans le champ d'application avec une méthode ou un constructeur très lisible.

Answer 13

Je suis d'accord avec Kilhoffer. Je préfère voir des noms de variables descriptives dans presque tous les contextes. Je vais abréger les noms de variables de plus de 20 caractères, généralement avec des mots dans le nom de la variable (par exemple: "SomeVeryLongVarValue").

Bien sûr, j’utilise aussi la notation hongroise chaque fois que je le peux. Je suis donc peut-être dans l’autre camp extrême qui consiste à essayer de rendre les noms de mes variables trop descriptifs, selon votre point de vue.

Answer 14

Je vais probablement être complètement hué, mais je voulais m'assurer que cette vue était entendue.

Bien que des noms de variable plus longs puissent être plus descriptifs, ils peuvent commencer à brouiller l’intention initiale du programme. Je pense que pour les éléments de l'API, il est important d'avoir des noms clairs et significatifs dans le contexte dans lequel ils seront utilisés.

Dans chaque fonction ou méthode, il s'agit souvent d'une histoire différente. J'essaie d'écrire moins et de le garder très concis. C’est ce que l’on appelle la programmation spartiate al M. Atwood et cet exemple astucieux . Oui, l’exemple est clairement truqué, mais il montre bien qu’avoir un peu moins de cérémonie peut réellement faciliter la lecture du programme.

Bonne chance.

Answer 15

Lors de la programmation, vous utilisez la syntaxe afin que les utilisateurs puissent la lire, la longueur des noms de variable, des méthodes, etc. est vraiment irréprochable.

Plus le contenu est verbeux, mieux c'est, normalement, avec un bon environnement de développement, vous devriez quand même terminer le code, de sorte que vous pouvez simplement cliquer sur "add_L" + TAB pour terminer l'appel à la méthode.

Answer 16

Je pense que le principal problème des abréviations est que toutes les personnes ne sont pas abrégées de la même manière . Ainsi, lorsque vous travaillez avec de nombreuses personnes, cela ne fait qu'augmenter la probabilité d'erreur lors du codage. Par exemple, si vous avez une constante pouvant être appelée SOMETHING_INTERFACE, certains développeurs pourraient l’abréger ainsi: SOMETHING_INTFACE, d’autres comme SOMETHING_IFACE ou SOMETHING_IF, SMTHING_IFACE ...

Avec seulement deux mots, vous pouvez avoir au moins une demi-douzaine de plus ou moins de "logique". abréviations possibles, donc je pense qu’il est préférable dans la plupart des cas d’écrire sans abréviations et avec plus de raisons si vous voulez avoir du code auto-documenté.

Les noms très longs peuvent parfois être agaçants, mais peuvent également être abrégés dans des portées très locales à l'aide de variables auxiliaires.

Answer 17

La plupart des gens lisent à vue, il ne faut pas plus de lire un mot, puis de lire une lettre individuelle. Donc, utilisez toujours des noms significatifs. Doivent-ils être des descriptions complètes de 7 mots, non, mais ils doivent être assez longs pour comprendre.

Je pourrais accepter add_loc (nom, coord), car ils sont assez longs pour que je puisse dire ce qu’ils sont. Dans add_loc (n, x, y), je m'opposerais à 'n' au lieu de nom. Je pourrais vivre avec X et Y car ce sont les noms de coordonnées acceptés.

Pour ceux qui ne sont pas familiers avec les systèmes de coordonnées, je pouvais voir où add_location (nom, coordonnées) aurait plus de sens.

En cas de doute, utilisez des noms plus longs.

Answer 18

"C'est correct pour résoudre les mystères du meurtre, mais vous ne devriez pas avoir besoin de comprendre le code. Vous devriez pouvoir le lire. " - Steve C. McConnell

Cela dit, si vous pensez que vous-même et tout le monde n'a pas besoin de noms de variable trop explicites, n'hésitez pas à les raccourcir.

Answer 19

Je suggère d'adopter une approche minimaliste. Utilisez-en un peu tout en vous assurant que votre code reste clair, concis et précis.

Answer 20

Hors de la portée, les noms tels que les constantes et les globales devraient avoir des noms descriptifs longs. Parfois, un nom vraiment long le rendra "odeur". juste assez pour signaler que sa présence est indésirable. C’est une bonne chose, car elle permettra 1 - d’éviter que les gens l’évitent, 2 - d’augmenter le nombre de personnes pressées pour reformuler le code et le faire disparaître.