5 ms·

On naming

85 points by lars512 15y ago

deleted 15y ago
[deleted]
tariq 15y ago
cool, and here i thought i was alone in needing to take time to name things correctly. had to name a variable earlier this week and even broke out the thesaurus. best i could muster was years_experienced_absolute :/
- akkartik 15y ago
  Sometimes when I have trouble coming up with a good name it's a sign that I need to rethink the surrounding code as well. Since naming is hard, I try to minimize the number of names I create. I think the number of names in a codebase is a measure of complexity.
  - chj 15y ago
    exactly.
  - snprbob86 15y ago
    Names are also critical to understanding. It's very similar to the phenomenon of notation (including maths, sciences, and, yes, programming languages themselves): "By relieving the brain of all unnecessary work, a good notation sets it free to concentrate on more advanced problems, and, in effect, increases the mental power of the race." -- P Davis and R Hersh The Mathematical Experience (Boston 1981). I know that my team spends an inordinate amount of time debatting the names of concepts. We've found that, since we're trying to build something unique, there aren't always words for the concepts we're building. Worse yet, there are words that are close, but not quite right! It's extremely difficult to write any code before everyone can hear a word and reach a common mental image. I've found that if you get the right names, the code is so much easier to write and reason about.
  - nu23 15y ago
    Sometimes though, not finding good names might just be an indication of the newness or non-standardized nature of the situation you are using the name in. Even in natural languages, there are concepts/situations which have names in one language and must be described using sentences in others. Trying to fit something into the currently popular wordlist might then be an artificial requirement.
  - deleted 15y ago
    [deleted]
jmonegro 15y ago
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.
j45 15y ago
Naming things to be clear in the beginning, stay clear as the system grows, is quite easily one of the hardest things in developing software. Over generalized or specific names cause far more confusion and productivity loss than we think. So take the time to learn what you're working on and how it works at the micro and macro level not only in the context of the application itself, but where and how the application fits in it's ecosystem. Learn the lingo that your software's ecosystem uses, instead of inventing, by accident or purpose, your own clever and tricky rationalizations ending up in even more confusing concepts and names describing the same things. The purpose of naming is similar to the purpose of software; creating clarity and empowerment, instead of more confusion and conceptual gymnastics.
cpeterso 15y ago
For more rigorous naming, Eric Evans (in his excellent book Domain-Driven Design: Tackling Complexity in the Heart of Software) recommends documenting (and maintaining) your product's "Ubiquitous Language". When developers (and the code), product managers, domain experts, and end users all use different terminology, then cross-discipline communication difficult and imprecise. A documented Ubiquitous Language enforces shared terminology (and meaning) for all communication within the team and in the code. http://domaindrivendesign.org/node/132 http://domaindrivendesign.org/node/132
mekoka 15y ago
This might be obvious to some, but I've literally only realized a few months ago that when I write text, I will consult a thesaurus, whereas for some reason I've neglected to do the same when I code. I would spend hours agonizing on how to call a module, wondering if I won't need the same word later for something else, or if it might be making things a bit ambiguous for the next guy. So I've started also using a thesaurus when I code and so far I'm happy with the results. It's been helpful in accurately framing some of the hazier concepts with interesting names. I also revisit the naming much less than I use to, because I'm comforted with the notion that if I couldn't find a better word with a thesaurus, then maybe there isn't an obvious one. I also now use words that are clear, but that I so far neglected to include in my programming vocabulary, because other more prevalent ones would jump in my mind and put a shadow on my naming creativity. So, if you need some help naming modules, functions, variables and db entities, a thesaurus could help. Though, take care to not abuse of it.
- panic 15y ago
  I do this too. Though my thesaurus doesn't always have the right technical meaning of certain words. I'd love to have a "programmer's thesaurus" with more detail on names that appear frequently in code. For one of the two hard problems in CS, the art of naming things has little reference material beyond raw source code.
- lars512 15y ago
  I'd never considered using a thesaurus for names, but it makes sense if the name you're starting with isn't quite right. Maybe something like Visual Wordnet (http://kylescholz.com/projects/wordnet/ http://kylescholz.com/projects/wordnet/) would be useful too.
- troels 15y ago
  I do it all the time. But then, English isn't my first language, so that probably makes it a more natural thing for me to do.
- vog 15y ago
  I'm using dict.cc for that purpose, which is not just a thesaurus but also a translation tool. Sometime I find the right words in my native language but not in english. Or, the synonyms are not satisfying, but switching between languages leads to words more loosely connected to my initial word, thus extending the search radius in a useful way.
medopal 15y ago
My colleagues (developers) laugh when I pause few seconds to think about a proper name for a Java method. But I take it seriously, finding a class or method with proper name is way easier than an ambiguous name> Even a proper name with misspelling is considered bad in my dictionary. Once in an interview, I asked the guy to write some code, he used variable names like "int ttttt=1;". I never saw him again!!
vrode 15y ago
Choosing the right metaphor in terms of OOP is equally important as well as the understanding the word's meaning and the implication of alternative meanings.
rplnt 15y ago
The first quote in the article; I thought it went like this: There are only two hard things in Computer Science: cache invalidation, naming things and off-by-one errors.
- TeMPOraL 15y ago
  I also thought it went like that, it's much better.
- caf 15y ago
  That version is just a well-known play on the original.
gmoes 15y ago
I agree, naming is important and often overlooked, check out this quote by Josh Bloch: http://www.elegantcoding.com/2011/07/software-frameworks-resistance-isnt.html#Names http://www.elegantcoding.com/2011/07/software-frameworks-res...
dhotson 15y ago
I find that thinking about good names for things can help guide you to design better code. As Lars mentioned—if something is hard to name, it's probably because the thing you're naming isn't very clearly defined, is a bad/mixed metaphor, or is just plain hard to understand. And if all else fails, there's always http://www.classnamer.com/ http://www.classnamer.com/ ;-)
raju 15y ago
I am glad someone wrote this article - Now I know I can point it to my colleagues who are often baffled at the amount of time I spend thinking about names :) I have found that when I can't find a good name for a method or a class, it's because I haven't really thought the reason for the same through. This is especially true for classes where I often realize that I am making the class do too much, or too little. This book, "Clean Code" by Robert Martin has it's second chapter dedicated to naming things. A whole chapter! The book, alone for that chapter is worth the money. If you haven't read it, I highly recommend it. http://www.amazon.com/Clean-Code-Handbook-Craftsmanship-ebook/dp/B001GSTOAM http://www.amazon.com/Clean-Code-Handbook-Craftsmanship-eboo...
- lars512 15y ago
  Steve McConnell's book "Code Complete" was an eye-opener for me. It also has a whole chapter on variable naming, and is worth a read. http://www.amazon.com/Code-Complete-Practical-Handbook-Construction/dp/0735619670/ref=sr_1_1?ie=UTF8&qid=1329769782&sr=8-1 http://www.amazon.com/Code-Complete-Practical-Handbook-Const...
rgc4 15y ago
Seriously, he suggests using i as a variable? I couldn't take him seriously after that.
- dhotson 15y ago
  It's an example of using a language's idioms. If you use i in a loop, there's no need to explain yourself since there's a common understanding as to what this means.
  - rgc4 15y ago
    If you use i, you're a bad programmer. You can't search for the variable name, you can't make sure it is used correctly everywhere. You're a bad person.
Detrus 15y ago
I think this problem comes up from the somewhat obsolete linear text nature of code. Instead of particular perfect names, we could be using tags. AbstractSingletonFactory is three tags. In some contexts I'd like to know it's a factory, in others I don't. The bigger problem is we haven't moved on from the simple text representation of code. And this overly simple tool, text, is influencing the way we're thinking here. The Humble Programmer phenomenon in action.

85 points by lars512 15y ago

deleted 15y ago

[deleted]

tariq 15y ago

cool, and here i thought i was alone in needing to take time to name things correctly. had to name a variable earlier this week and even broke out the thesaurus. best i could muster was years_experienced_absolute :/

akkartik 15y ago
Sometimes when I have trouble coming up with a good name it's a sign that I need to rethink the surrounding code as well. Since naming is hard, I try to minimize the number of names I create. I think the number of names in a codebase is a measure of complexity.
- chj 15y ago
  exactly.
- snprbob86 15y ago
  Names are also critical to understanding. It's very similar to the phenomenon of notation (including maths, sciences, and, yes, programming languages themselves): "By relieving the brain of all unnecessary work, a good notation sets it free to concentrate on more advanced problems, and, in effect, increases the mental power of the race." -- P Davis and R Hersh The Mathematical Experience (Boston 1981). I know that my team spends an inordinate amount of time debatting the names of concepts. We've found that, since we're trying to build something unique, there aren't always words for the concepts we're building. Worse yet, there are words that are close, but not quite right! It's extremely difficult to write any code before everyone can hear a word and reach a common mental image. I've found that if you get the right names, the code is so much easier to write and reason about.
- nu23 15y ago
  Sometimes though, not finding good names might just be an indication of the newness or non-standardized nature of the situation you are using the name in. Even in natural languages, there are concepts/situations which have names in one language and must be described using sentences in others. Trying to fit something into the currently popular wordlist might then be an artificial requirement.
- deleted 15y ago
  [deleted]

jmonegro 15y ago

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.

j45 15y ago

Naming things to be clear in the beginning, stay clear as the system grows, is quite easily one of the hardest things in developing software. Over generalized or specific names cause far more confusion and productivity loss than we think. So take the time to learn what you're working on and how it works at the micro and macro level not only in the context of the application itself, but where and how the application fits in it's ecosystem. Learn the lingo that your software's ecosystem uses, instead of inventing, by accident or purpose, your own clever and tricky rationalizations ending up in even more confusing concepts and names describing the same things. The purpose of naming is similar to the purpose of software; creating clarity and empowerment, instead of more confusion and conceptual gymnastics.

cpeterso 15y ago

For more rigorous naming, Eric Evans (in his excellent book Domain-Driven Design: Tackling Complexity in the Heart of Software) recommends documenting (and maintaining) your product's "Ubiquitous Language". When developers (and the code), product managers, domain experts, and end users all use different terminology, then cross-discipline communication difficult and imprecise. A documented Ubiquitous Language enforces shared terminology (and meaning) for all communication within the team and in the code. http://domaindrivendesign.org/node/132 http://domaindrivendesign.org/node/132

mekoka 15y ago

This might be obvious to some, but I've literally only realized a few months ago that when I write text, I will consult a thesaurus, whereas for some reason I've neglected to do the same when I code. I would spend hours agonizing on how to call a module, wondering if I won't need the same word later for something else, or if it might be making things a bit ambiguous for the next guy. So I've started also using a thesaurus when I code and so far I'm happy with the results. It's been helpful in accurately framing some of the hazier concepts with interesting names. I also revisit the naming much less than I use to, because I'm comforted with the notion that if I couldn't find a better word with a thesaurus, then maybe there isn't an obvious one. I also now use words that are clear, but that I so far neglected to include in my programming vocabulary, because other more prevalent ones would jump in my mind and put a shadow on my naming creativity. So, if you need some help naming modules, functions, variables and db entities, a thesaurus could help. Though, take care to not abuse of it.

panic 15y ago
I do this too. Though my thesaurus doesn't always have the right technical meaning of certain words. I'd love to have a "programmer's thesaurus" with more detail on names that appear frequently in code. For one of the two hard problems in CS, the art of naming things has little reference material beyond raw source code.
lars512 15y ago
I'd never considered using a thesaurus for names, but it makes sense if the name you're starting with isn't quite right. Maybe something like Visual Wordnet (http://kylescholz.com/projects/wordnet/ http://kylescholz.com/projects/wordnet/) would be useful too.
troels 15y ago
I do it all the time. But then, English isn't my first language, so that probably makes it a more natural thing for me to do.
vog 15y ago
I'm using dict.cc for that purpose, which is not just a thesaurus but also a translation tool. Sometime I find the right words in my native language but not in english. Or, the synonyms are not satisfying, but switching between languages leads to words more loosely connected to my initial word, thus extending the search radius in a useful way.

medopal 15y ago

My colleagues (developers) laugh when I pause few seconds to think about a proper name for a Java method. But I take it seriously, finding a class or method with proper name is way easier than an ambiguous name> Even a proper name with misspelling is considered bad in my dictionary. Once in an interview, I asked the guy to write some code, he used variable names like "int ttttt=1;". I never saw him again!!

vrode 15y ago

Choosing the right metaphor in terms of OOP is equally important as well as the understanding the word's meaning and the implication of alternative meanings.

rplnt 15y ago

The first quote in the article; I thought it went like this: There are only two hard things in Computer Science: cache invalidation, naming things and off-by-one errors.

TeMPOraL 15y ago
I also thought it went like that, it's much better.
caf 15y ago
That version is just a well-known play on the original.

gmoes 15y ago

I agree, naming is important and often overlooked, check out this quote by Josh Bloch: http://www.elegantcoding.com/2011/07/software-frameworks-resistance-isnt.html#Names http://www.elegantcoding.com/2011/07/software-frameworks-res...

dhotson 15y ago

I find that thinking about good names for things can help guide you to design better code. As Lars mentioned—if something is hard to name, it's probably because the thing you're naming isn't very clearly defined, is a bad/mixed metaphor, or is just plain hard to understand. And if all else fails, there's always http://www.classnamer.com/ http://www.classnamer.com/ ;-)

raju 15y ago

I am glad someone wrote this article - Now I know I can point it to my colleagues who are often baffled at the amount of time I spend thinking about names :) I have found that when I can't find a good name for a method or a class, it's because I haven't really thought the reason for the same through. This is especially true for classes where I often realize that I am making the class do too much, or too little. This book, "Clean Code" by Robert Martin has it's second chapter dedicated to naming things. A whole chapter! The book, alone for that chapter is worth the money. If you haven't read it, I highly recommend it. http://www.amazon.com/Clean-Code-Handbook-Craftsmanship-ebook/dp/B001GSTOAM http://www.amazon.com/Clean-Code-Handbook-Craftsmanship-eboo...

lars512 15y ago
Steve McConnell's book "Code Complete" was an eye-opener for me. It also has a whole chapter on variable naming, and is worth a read. http://www.amazon.com/Code-Complete-Practical-Handbook-Construction/dp/0735619670/ref=sr_1_1?ie=UTF8&qid=1329769782&sr=8-1 http://www.amazon.com/Code-Complete-Practical-Handbook-Const...

rgc4 15y ago

Seriously, he suggests using i as a variable? I couldn't take him seriously after that.

dhotson 15y ago
It's an example of using a language's idioms. If you use i in a loop, there's no need to explain yourself since there's a common understanding as to what this means.
- rgc4 15y ago
  If you use i, you're a bad programmer. You can't search for the variable name, you can't make sure it is used correctly everywhere. You're a bad person.

Detrus 15y ago

I think this problem comes up from the somewhat obsolete linear text nature of code. Instead of particular perfect names, we could be using tags. AbstractSingletonFactory is three tags. In some contexts I'd like to know it's a factory, in others I don't. The bigger problem is we haven't moved on from the simple text representation of code. And this overly simple tool, text, is influencing the way we're thinking here. The Humble Programmer phenomenon in action.