Comment "l'auto-documentation" code peut être sans être ennuyeux?

Question

Je ne suis pas sûr de ce que les meilleures pratiques sont ici, mais je vois souvent abrégée des noms de variables en particulier lorsque la portée est faible. Donc (à utiliser de simples Ruby exemples) au lieu de def add_location(name, coordinates),, je vois les choses comme def add_loc(name, coord)-et je pourrais même voir quelque chose comme def add_loc(n, x, y). J'imagine que plus les noms des pneus d'une personne dont l'habitude de voir les abréviations.

Ne verbosité aider à la lisibilité, ou est-il juste blesser les yeux de tout le monde?-Les gens préfèrent les abréviations et les noms raccourcis sur des noms plus longs?

Answer 1

Personnellement, je préférerais voir des noms plus longs que signifie réellement quelque chose sans avoir à déterminer le contexte de la première. Bien sûr, les variables qui ne permettent pas de sens réel, tels que les compteurs, j'ai toujours utiliser un petit pas de sens, les noms de variables (comme i ou x), mais sinon le niveau de verbosité est la clarté , la plupart du temps. Cela est particulièrement vrai avec les Api publiques.

Cela peut être pris trop loin, cependant. J'ai vu certains de code visual basic dans le passé de cette façon ridicule. La modération comme tout le reste!

Answer 2

J'ai fait de longs noms de variable tout le temps, après tout les Ide modernes et texteditors ont achèvement, donc il n'y a rien de mal avec l'aide d' index au lieu de cela, si je. La seule exception que j'ai est lorsque vous traitez avec les coordonnées de b/c x et y faire le plus de sens là.

Answer 3

Une variable doit être donnée le plus rapidement possible le nom adéquatement transmet son but.

Sur-le niveau de verbosité tend à dissimuler la syntaxe, et la syntaxe est importante.

Tout un programme (ou d'une application/système) variables doit être nommé avec l'harmonie de style et autres choses semblables doivent être nommés de la même façon. Si une convention existe au sein de la communauté linguistique, il doit être observé (afin de ne pas camelCaseRubyVariableNames) sauf s'il y a quelque raison de ne pas le faire.

Abréviations, si utilisé, doit être appliquée uniformément partout et si spécifiques au domaine, doit être enregistré quelque part. Si quelqu'un va passer toute quantité de temps avec le code puis ils vont bientôt apprendre.

Si vous avez besoin de combiner autant d'en tant que cinq ou six mots pour nommer une variable alors je suggère que vous pourriez être à la recherche à une odeur de code et la routine vous travaillez peut bénéficier d'un peu de travail.

Mais surtout, si vous êtes conscient des pièges et fait réfléchir sur ce que vous écrivez, les chances sont que votre code sera raisonnable. Imaginez-vous décrire la fonction vous travaillez sur un nouveau collègue - le moins que vous pense que vous auriez besoin de le dire, le mieux le code est probablement le cas.

Answer 4

Jamais abbr.

Answer 5

Essayez de lire votre propre code 1 an plus tard. Vous verrez à la fois la valeur de l'auto de documenter les noms de variables, et la valeur des commentaires de code ( et spécialement de la valeur de nettoyer le code )

Lorsque vous prenez quelqu'un d'autre le code source et que vous ne comprenez pas c'est que c'est facile de penser "eh Bien, il n'est pas aussi bon programmeur, comme je suis", Mais quand vous vous rendez compte que votre propre code est difficile à lire, vous aller comme: "a quoi je thinkng?"

Dans le long terme, le niveau de verbosité aide à la gestion. Pour faire court une ligne de script, vous pouvez toujours utiliser "setLocNm" au lieu de setLocationName"

N'importe quel imbécile peut écrire du code que l'ordinateur peut comprendre. Les bons programmeurs d'écrire du code que les humains peuvent comprendre. -Martin Fowler