4 ms·

What I like to do is add a variables.txt file to the root of the project as a sort of legend for any unconventional variables I have to name. I try to stay as r

What I like to do is add a variables.txt file to the root of the project as a sort of legend for any unconventional variables I have to name. I try to stay as relevant as possible, but sometimes 'anospic' is better than 'average_numbers_picked'. Good or bad, it works.

roryokane 15y ago
Another possible solution is to put the full variable name in a comment next to the first declaration, in languages with variable declarations. Like this: double anospic; // average numbers picked Just raising it as an option; I haven’t actually used that style much myself. With the code I’ve been writing recently I haven’t had any problems so far giving variables names as long as I’d like.
- jmonegro 15y ago
  That's a good idea for languages that use that convention (I'd use it with objective-c if xcode didn't make using long variables so easy), but I mostly work with ruby.
  - pi18n 15y ago
    anospic ||= ... # average numbers picked The Ruby convention would be to write out the variable with underscores anyway, just sayin'.
danssig 15y ago
If you use a decent IDE, having longer variable names is nearly no cost.
- snprbob86 15y ago
  I don't buy this argument, but you're in good company holding this belief. Generally, I find that long names fall into three categories: 1) refactoring opportunities Use more namespaces, write smaller functions, embrace lexical scoping, etc. You don't need to call something a foo-bar-frobber when it's being used in the foo-bar context, just call it a frobber. 2) line noise If you're only using the frobber within a two line function, and it is initialized via create-frobber, do you really need to spell it out? f or x will do. If your function grows, rename the variable. Or refactor! 3) an absentee synonym Maybe you've got a monster-which-attempts-to-defeat-player, when you really need a baddie. Or maybe the word you need doesn't exist yet? It's rare, but sometimes you really do need to invent or repurpose a word. ... I always feel dirty when I have a long variable name. pg writes about this in On Lisp: long names feel heavier. They might be super cheap to call, but because the name is long, you're less likely to call it. Furthermore, I much rather adhere to a line length limit, as I find wrapping lines far harder to read than lines with short variable names. Long names makes this harder. All that said, I almost never use abbreviations other than standin variables like a single letter. The only exception to this is well known abbreviations, like for your most commonly used utility functions or for objects which are extremely common in your problem domain. Such a set of abbreviations becomes a part of the language you share between your compiler and your team.
  - gbog 15y ago
    What you say is true but only for variable names. Functions can have longer names, especially those called far away by some client code. For me the rule off thumb is that if you need a comment, you are better off with a longer name.
  - lemming 15y ago
    f or x will do. If your function grows, rename the variable. Why would you just not give it a reasonable name to begin with? Why not call your variable frobber? The only possible reason for not doing so is that you're using an editor that makes you type it every single time. I insist that calling your Frobber variable frobber is strictly easier to understand than f or x. Why not t? Or sdfsdg? None of them make any sense to someone reading the code, and it increases the amount the reader of the code has to keep in their short-term memory, making it more challenging to understand. pg writes about this in On Lisp: long names feel heavier. They might be super cheap to call, but because the name is long, you're less likely to call it. Even if pg wrote it this is patently absurd, and it's endemic in lisp code which contributes greatly to the famously write-only nature of lisp. Again, if you're using a decent editor, there is no reason to call your UserDetails object anything but user-details (or maybe details if you're in a context only relating to users).
    - snprbob86 15y ago
      > The only possible reason for not doing so is that you're using an editor that makes you type it every single time. Here's some C: for (int player_index = 0; player_index < players.length; player_index++) { int rank = player_index + 1; render_score(rank, players[player_index].name); } Blah. So much for the brain to parse! for (int p = 0; p < players.length; p++) { int rank = p + 1; render_score(rank, players[p].name); } I find that much, much easier to parse in my head. The definition of p is available without any backtracking. The word "player" appears five fewer times, reducing confusion with the players array. This is a small case. If this code were to start to grow, and the definition of p and its usages start to grow appart, it's trivial to replace.... but it's probably better for you to refactor.
- jmonegro 15y ago
  That is true. When I do Objective-c using Xcode (glorious IDE), variable length is a non-issue. Ruby on TextMate is a different story, though.
panic 15y ago
In what situation is the name 'anospic' acceptable? In a small scope, 'avg' or 'average' would probably read better. In a larger scope, you'd have to remember that it really means 'average_numbers_picked' each time it appears -- why not just use that name?
- jmonegro 15y ago
  Once it's written, I always make the association between 'anospic' and 'average numbers picked' (using that as an example). I try to make the names both human-readable and at least somewhat related (a:average nos:numbers pic:picked). Keep in mind that I don't do this with client work or anything that might land on the hands of another developer.
  - thebooktocome 15y ago
    You don't always know from the beginning what's going to land on the hands of another developer, and if something (even a personal project) did shift from you to someone else, you're going to not be very highly incentivized to change things then.
  - liotier 15y ago
    There is always another developer - even if it is only some future you. When you pick up that piece of code in three years, hoping to improve or reuse some of it, it will take you three minutes to remember what "anospic" was supposed to mean...
    - FreeFull 15y ago
      Which is why the variables.txt exists. A quick lookup in good documentation tends to make things clear.
      - eisbaw 15y ago
        Yes, another level of indirection is always a good way to increase the amount of mental cache misses.
lars512 15y ago
Good API documentation serves a bit like a glossary too. I'd be worried about the double-maintenance problem, but I suppose it's always there between code and docs. As long as you name things consistently, I can see how it'd be useful.

roryokane 15y ago

Another possible solution is to put the full variable name in a comment next to the first declaration, in languages with variable declarations. Like this: double anospic; // average numbers picked Just raising it as an option; I haven’t actually used that style much myself. With the code I’ve been writing recently I haven’t had any problems so far giving variables names as long as I’d like.

jmonegro 15y ago
That's a good idea for languages that use that convention (I'd use it with objective-c if xcode didn't make using long variables so easy), but I mostly work with ruby.
- pi18n 15y ago
  anospic ||= ... # average numbers picked The Ruby convention would be to write out the variable with underscores anyway, just sayin'.

danssig 15y ago

If you use a decent IDE, having longer variable names is nearly no cost.

snprbob86 15y ago
I don't buy this argument, but you're in good company holding this belief. Generally, I find that long names fall into three categories: 1) refactoring opportunities Use more namespaces, write smaller functions, embrace lexical scoping, etc. You don't need to call something a foo-bar-frobber when it's being used in the foo-bar context, just call it a frobber. 2) line noise If you're only using the frobber within a two line function, and it is initialized via create-frobber, do you really need to spell it out? f or x will do. If your function grows, rename the variable. Or refactor! 3) an absentee synonym Maybe you've got a monster-which-attempts-to-defeat-player, when you really need a baddie. Or maybe the word you need doesn't exist yet? It's rare, but sometimes you really do need to invent or repurpose a word. ... I always feel dirty when I have a long variable name. pg writes about this in On Lisp: long names feel heavier. They might be super cheap to call, but because the name is long, you're less likely to call it. Furthermore, I much rather adhere to a line length limit, as I find wrapping lines far harder to read than lines with short variable names. Long names makes this harder. All that said, I almost never use abbreviations other than standin variables like a single letter. The only exception to this is well known abbreviations, like for your most commonly used utility functions or for objects which are extremely common in your problem domain. Such a set of abbreviations becomes a part of the language you share between your compiler and your team.
- gbog 15y ago
  What you say is true but only for variable names. Functions can have longer names, especially those called far away by some client code. For me the rule off thumb is that if you need a comment, you are better off with a longer name.
- lemming 15y ago
  f or x will do. If your function grows, rename the variable. Why would you just not give it a reasonable name to begin with? Why not call your variable frobber? The only possible reason for not doing so is that you're using an editor that makes you type it every single time. I insist that calling your Frobber variable frobber is strictly easier to understand than f or x. Why not t? Or sdfsdg? None of them make any sense to someone reading the code, and it increases the amount the reader of the code has to keep in their short-term memory, making it more challenging to understand. pg writes about this in On Lisp: long names feel heavier. They might be super cheap to call, but because the name is long, you're less likely to call it. Even if pg wrote it this is patently absurd, and it's endemic in lisp code which contributes greatly to the famously write-only nature of lisp. Again, if you're using a decent editor, there is no reason to call your UserDetails object anything but user-details (or maybe details if you're in a context only relating to users).
  - snprbob86 15y ago
    > The only possible reason for not doing so is that you're using an editor that makes you type it every single time. Here's some C: for (int player_index = 0; player_index < players.length; player_index++) { int rank = player_index + 1; render_score(rank, players[player_index].name); } Blah. So much for the brain to parse! for (int p = 0; p < players.length; p++) { int rank = p + 1; render_score(rank, players[p].name); } I find that much, much easier to parse in my head. The definition of p is available without any backtracking. The word "player" appears five fewer times, reducing confusion with the players array. This is a small case. If this code were to start to grow, and the definition of p and its usages start to grow appart, it's trivial to replace.... but it's probably better for you to refactor.
jmonegro 15y ago
That is true. When I do Objective-c using Xcode (glorious IDE), variable length is a non-issue. Ruby on TextMate is a different story, though.

panic 15y ago

In what situation is the name 'anospic' acceptable? In a small scope, 'avg' or 'average' would probably read better. In a larger scope, you'd have to remember that it really means 'average_numbers_picked' each time it appears -- why not just use that name?

jmonegro 15y ago
Once it's written, I always make the association between 'anospic' and 'average numbers picked' (using that as an example). I try to make the names both human-readable and at least somewhat related (a:average nos:numbers pic:picked). Keep in mind that I don't do this with client work or anything that might land on the hands of another developer.
- thebooktocome 15y ago
  You don't always know from the beginning what's going to land on the hands of another developer, and if something (even a personal project) did shift from you to someone else, you're going to not be very highly incentivized to change things then.
- liotier 15y ago
  There is always another developer - even if it is only some future you. When you pick up that piece of code in three years, hoping to improve or reuse some of it, it will take you three minutes to remember what "anospic" was supposed to mean...
  - FreeFull 15y ago
    Which is why the variables.txt exists. A quick lookup in good documentation tends to make things clear.
    - eisbaw 15y ago
      Yes, another level of indirection is always a good way to increase the amount of mental cache misses.

lars512 15y ago

Good API documentation serves a bit like a glossary too. I'd be worried about the double-maintenance problem, but I suppose it's always there between code and docs. As long as you name things consistently, I can see how it'd be useful.