4 ms·

Good naming is hard because you are using the wrong tool. Names in code, and even in the business world, are usually abbreviations for much more complex things.

Good naming is hard because you are using the wrong tool. Names in code, and even in the business world, are usually abbreviations for much more complex things. You should not be looking for too much meaning from the name itself. Most words have many meanings, so trying to string together some verbs and nouns to describe complex behavior will almost always fail. A BDD test suite is far more suited to tell you what the abbreviated name really stands for than trying to deduce it from the name itself. One exception to this could be programming idioms, for example using 'i' as a counter in a loop which anyone with experience recognizes without even thinking. To many programmers, 'i' has become a word with quite a complex meaning itself: a) I'm a number b) I will be incremented c) I will be used in a loop d) I will be tested against to end the loop. Try naming that accurately without ending up with a really long variable name.

jstimpfle 10y ago
Programming mostly in Python and some C these days, for me names are the most important place to put meaning in. The trick is being systematic. And consistent in the small. Short names and (at first) non-telling names are not a problem. It makes no sense to use (predominantly) very long descriptive names, not because they are harder to type, but because a long name is and indication that it's not an established concept, not a recurring theme across the code pase. So my habit has become to just choose a one-word name for this vague but probably important concept I have, even if it's not the best name. I put a comment on the datatype declaration, explaining in detail the meaning of that thing. Maybe later I will come up with a better name, so I will just switch to that name. Or the comment gets improved. It's about growing clear concepts. After some time that single-word name will be a natural thing to use for that concept.
- natch 10y ago
  Fix-it-later leads to shoddy code though. If you can have a clear understanding of the important concept (instead of a vague understanding) that can be reflected in a good name. Good name meaning one that is descriptive, unambiguous, and reveals a crisp, not vague, concept. Then with that good name, when you write the code the first time, the clarity of the concept will help you avoid logic pitfalls and messy constructs. Not to say comments are always bad, but probably a comment won't be needed, because the name itself will reveal the intent. Then later, when someone does come and edit the code, instead of having to come up with a better name, they can focus on whatever they came there for, and they can do so with a better understanding of each variable and what is going on. The difference between the two approaches is really about where you spend your extra time related to naming. In my approach, you spend a little extra time up front. But it begins paying dividends immediately, as you continue writing the very first version of the code; it is easier to write clearly and correctly. In your approach, you spend less time up front, and pour the code out faster, which might seem like a great thing. You also see an immediate payoff, because your process is fast. But then you (or someone who comes behind you) has to pay a heavy bill of technical debt. When I read your comment I read it as a description of what your current practice is, not something that has been thought through a lot. Growing clear concepts is a great way to think about it, so that's a good line to continue with imho. I just think that part can and should be done up front. Sometimes it's worth a short conversation with another developer to see if you can agree on a good definition reflected in a clear name. But you're also right that sometimes single word names work fine. And sometimes concepts are just clear and don't need much thought. Obviously those ones we can agree on. I'm more focused on the more difficult, or more vague ones, as a place where I think up-front quality naming is better than having the "fix-it-later" approach.
  - jstimpfle 10y ago
    Yeah I didn't mean to imply that I pick bad names intentionally. Of course I pick the best name that I can come up with. But when I'm doing something I haven't done before, it's hard to judge whether a name is any good, maybe because I don't actually know precisely what I'm doing in the first place. In these cases I err on the side of short names (preferably non-composite) because I know that making a longer name will not help. I just use that new name a little in a more exploratory type of programming. When it sticks it was a good choice. Examples: tree, spec, coverage, identity, isomorphism, object, struct, key, value, tag... These names need context, but they can turn out to be good names because they are short and distinct. When the name doesn't stick and I can't come up with a better one, maybe I should do something entirely different.
crdoconnor 10y ago
"for example using 'i' as a counter in a loop which anyone with experience recognizes without even thinking." This actually isn't too bad provided the loop's scope is small and it is obvious from context what it is doing. It's variable names which could have a variety of different meanings used in larger contexts and scopes - that's when maintainer confusion really sets in.
mannykannot 10y ago
One way you can end up using the wrong tool is through trying to cram every relevant fact about a variable or function into its name because you have been told comments are bad.
vertex-four 10y ago
Of course, the actual solution to using i as a counter in a loop is almost always to elide the counter entirely, using an iterator. Expanding on that principle - if you have something that seems to evade a good name, perhaps you're at the wrong level of abstraction.
- c22 10y ago
  Or instead of "i" use "iteration"? Whatever, I use "f" for all my file handlers too.

jstimpfle 10y ago

Programming mostly in Python and some C these days, for me names are the most important place to put meaning in. The trick is being systematic. And consistent in the small. Short names and (at first) non-telling names are not a problem. It makes no sense to use (predominantly) very long descriptive names, not because they are harder to type, but because a long name is and indication that it's not an established concept, not a recurring theme across the code pase. So my habit has become to just choose a one-word name for this vague but probably important concept I have, even if it's not the best name. I put a comment on the datatype declaration, explaining in detail the meaning of that thing. Maybe later I will come up with a better name, so I will just switch to that name. Or the comment gets improved. It's about growing clear concepts. After some time that single-word name will be a natural thing to use for that concept.

natch 10y ago
Fix-it-later leads to shoddy code though. If you can have a clear understanding of the important concept (instead of a vague understanding) that can be reflected in a good name. Good name meaning one that is descriptive, unambiguous, and reveals a crisp, not vague, concept. Then with that good name, when you write the code the first time, the clarity of the concept will help you avoid logic pitfalls and messy constructs. Not to say comments are always bad, but probably a comment won't be needed, because the name itself will reveal the intent. Then later, when someone does come and edit the code, instead of having to come up with a better name, they can focus on whatever they came there for, and they can do so with a better understanding of each variable and what is going on. The difference between the two approaches is really about where you spend your extra time related to naming. In my approach, you spend a little extra time up front. But it begins paying dividends immediately, as you continue writing the very first version of the code; it is easier to write clearly and correctly. In your approach, you spend less time up front, and pour the code out faster, which might seem like a great thing. You also see an immediate payoff, because your process is fast. But then you (or someone who comes behind you) has to pay a heavy bill of technical debt. When I read your comment I read it as a description of what your current practice is, not something that has been thought through a lot. Growing clear concepts is a great way to think about it, so that's a good line to continue with imho. I just think that part can and should be done up front. Sometimes it's worth a short conversation with another developer to see if you can agree on a good definition reflected in a clear name. But you're also right that sometimes single word names work fine. And sometimes concepts are just clear and don't need much thought. Obviously those ones we can agree on. I'm more focused on the more difficult, or more vague ones, as a place where I think up-front quality naming is better than having the "fix-it-later" approach.
- jstimpfle 10y ago
  Yeah I didn't mean to imply that I pick bad names intentionally. Of course I pick the best name that I can come up with. But when I'm doing something I haven't done before, it's hard to judge whether a name is any good, maybe because I don't actually know precisely what I'm doing in the first place. In these cases I err on the side of short names (preferably non-composite) because I know that making a longer name will not help. I just use that new name a little in a more exploratory type of programming. When it sticks it was a good choice. Examples: tree, spec, coverage, identity, isomorphism, object, struct, key, value, tag... These names need context, but they can turn out to be good names because they are short and distinct. When the name doesn't stick and I can't come up with a better one, maybe I should do something entirely different.

crdoconnor 10y ago

"for example using 'i' as a counter in a loop which anyone with experience recognizes without even thinking." This actually isn't too bad provided the loop's scope is small and it is obvious from context what it is doing. It's variable names which could have a variety of different meanings used in larger contexts and scopes - that's when maintainer confusion really sets in.

mannykannot 10y ago

One way you can end up using the wrong tool is through trying to cram every relevant fact about a variable or function into its name because you have been told comments are bad.

vertex-four 10y ago

Of course, the actual solution to using i as a counter in a loop is almost always to elide the counter entirely, using an iterator. Expanding on that principle - if you have something that seems to evade a good name, perhaps you're at the wrong level of abstraction.

c22 10y ago
Or instead of "i" use "iteration"? Whatever, I use "f" for all my file handlers too.