Many programmers have a natural preference for short variable and method names. I doubt many would recognize this preference as a trade of brevity for clarity, but that’s often exactly the result. This is especially true if you subscribe to the ridiculous Church of 80-character Lines.
It need not be that way. Writing terse code can be a joy even if you spell things out in abundant detail. Modern programming languages are expressive enough that what you save in laborious boilerplate can be spent on clarity — and you’ll still have plenty of lines left over for a dance.
And most certainly, you’ll hardly ever need to abbreviate anything. I cringe when I see ext for extension, cp for copy, or worse, application-specific abbreviations sure to be forgotten two months after you left the project.
At times being exceedingly clear will seem almost silly at first glance. The name of the method or variable can be longer than the operation being performed! But the silliness quickly dissipates the first time you return to a piece of code and know exactly what it does.
Here are a few examples of long method names from the new Basecamp code base:
def make_person_an_outside_subscriber_if_all_accesses_revoked
person.update_attribute(:outside_subscriber, true) if person.reload.accesses.blank?
end
def shift_records_upward_starting_at(position)
positioned_records.update_all "position = position - 1",
["position >= ?", position]
end
def someone_else_just_finished_writing?(document)
if event = document.current_version_event
!event.by_current_creator? and event.updated_at > 1.minute.ago
end
end
If you work hard at being clear in your naming, you’ll also rarely need to write comments for the code. Comments are generally only needed when you failed to be clear enough in naming. Treat them as a code smell.
Don Schenck
on 10 Sep 12Always remember: A program IS NOT communication between a human and the machine.
It’s a communication between a developer and the next developer.
Mike Desjardins
on 10 Sep 12I like to put it this way: “the variable names are the comments.”
Nano
on 10 Sep 12This is one thing I’ve taken from my Objective-C learning and applied to all my Ruby, JS, CSS work since. My colleagues still jab me for it, but not once have they asked me what a method does or a what a variable is for or what a CSS property is referencing.
Jeremy Nicoll
on 10 Sep 12On the other hand if your method name is almost as long or longer than the code inside it, then you probably are being a bit too verbose in the naming…
Will
on 10 Sep 12This is precisely one of the reasons I like Objective-C and the Cocoa API
Dmitry
on 10 Sep 12Ditto on ObjC influence, trying to tie that up in my python code.
David, I wonder about auto-completion though, do you use big IDEs with introspection at 37 at all, or rely on text editor completion?
DHH
on 10 Sep 12Jeremy, I don’t think so at all. The method name explains the intention, the code the implementation. I’ve on many a occasion had longer names than implementation. This is especially true for explaining variables as well.
someone_else_just_finished_writing? is completely divorced from whether we implement this using events and how long “just” is.DHH
on 10 Sep 12Dmitry, most methods are not called enough times to warrant any automation. I have escape-key completion in TextMate and that’s been fine.
Xavier Noria
on 10 Sep 12Reminded me of config.active_record.auto_explain_threshold_in_seconds :).
Steven Garrity
on 10 Sep 12CRC
on 10 Sep 12@Don: Amen brother!
josh susser
on 10 Sep 12These are the good old IntentionRevealingMethod, IntentionRevealingSelector and RoleSuggesting[Instance,Temporary]VariableName patterns from Kent Beck’s classic Smalltalk Best Practice Patterns. I totally agree that those are best practices.
Brook Riggio
on 10 Sep 12Ha, great examples. I included this idea as “n00b mistake #3” in a recent post: http://www.readysetrails.com/index.php/2111/5-mistakes-that-make-you-look-like-a-rails-n00b/
I really like that comment on separating the intention from the implementation.
Thanks for the clear examples!
DHH
on 10 Sep 12Josh, Smalltalk Best Practice Patterns is the bible on this. Never have I read a book that included so much good advice about programming in such a little tome. It’s golden.
Erich
on 10 Sep 12Though I do think that we, as developers, do tend to label methods too opaquely, in this case the phrase, “method names only a Dane could love” comes to mind.
jjt
on 10 Sep 12I’m not dogmatic about it, but I like 80-char lines as a general rule because I can set my terminal and editor windows/panes/etc to a known width and stack 2 beside each other in 1280 pixels at a comfortable font size and be able to see all of the code without resorting to wrapping.
This won’t hold for every language and coding style, but it seems like most of my lines are around 20-60 chars and I would end up with a lot of wasted screen space in my editor if I had a large width set.
Spicer Matthews
on 10 Sep 12David, Thanks for the post. I could not agree more. In fact I posted something simular recently.
http://cloudmanic.com/blog/5/coding-should-be-like-writing-a-book
and
http://spicermatthews.com/blogs/geek/being_an_elegant_business_programmer
As always I really enjoy your blunt, simple, and to the point writing style. You send in a few lines what I had to say in two blog posts.
Austin Schneider
on 10 Sep 12I’m a big fan of verbose variable and method names. However, I’ve noticed that as the design of my code improves, the less verbose/shorter my naming would get. On the flip side, if I notice a method getting really long, or including the word ‘and’ or ‘or’ it’s a hint to me that it may need some refactoring.
Radex
on 10 Sep 12I’d say one big exception: APIs (frameworks, libs) that are used all the time. When you use a method all the time, long names are very annoying and the benefit of clarity is almost zero.
For instance, drawing in Cocoa is extremely tedious.
Take, drawing a line on a bezier path:
Ugh. Trust me, when you try to make a complex shape, it becomes decipherable after a week.
I had to create a set of helpers to make it bearable.
So for this example, it could be something like:
(yes, using relativeLineToPath is better, but still PITA)
Ferenc Mihaly
on 10 Sep 12As you yourself mention as the “Church of 80-character Lines”, many naming mistakes in programming are essentially bad habits: things programmers were forced to do in the past due to technical limitations, but are no longer needed or appropriate today. People are still doing it either out of inertia or because, in certain programming circles at least, it became part of the culture, “just the way things are done”.
Austin Schneider
on 10 Sep 12Radex, Often application method names are longer due to the use cases of your app and the domain language itself. For example, `make_person_an_outside_subscriber_if_all_accesses_revoked` is very much Basecamp-specific. As reusable/decoupled bits of code break out into classes/modules/libraries/frameworks/apis/etc, that’s typically where the names get shorter.
David Jones
on 10 Sep 12I’ve just read your article on clarity over brevity & got some new idea about this issue.
Daniel
on 10 Sep 12Given the choice I would rather have the object instance document the method. So instead of do_something_to_object I would rather call object.do_something. Nevertheless, I agree with everything you said, really great stuff. It’s rather unfortunate that so many look how long the current line is rather than asking them selves, is this more readable than before.
Brad
on 10 Sep 12Regarding the 80 character side-topic: It’d be interesting to see the average number of characters per line in most published books these days (or some kind of variable equivalent for e-books). 80 characters shouldn’t be an ironclad rule, you’re right, but on the flip side it’s worth remembering that our eyes are trained to read text that isn’t incredibly wide.
GregT
on 10 Sep 12‘Clean Code’ talks about this, especially the notion that if you name everything properly, you shouldn’t need comments. One of my favorite programming books. I’m gonna check out the SmallTalk one now!
Igor Kolomiets
on 10 Sep 12You Ruby people were making fun of us Java programmers all these years for doing exactly this!
Bill
on 10 Sep 12I have always maintained this position for most of my programming career.
It is a lot less common today, but years ago you saw a lot more programmers that didn’t type well. As a result they were always trying to shorten things.
We actually put into our coding standards one time the list of acceptable abbreviations to appease this crowd, and keep them somewhat reigned in on the cp2svr kind of junk.
Dan
on 10 Sep 12spec.lines.each.join(’_’) => API
Lukasz
on 10 Sep 12Ahh bullshit! Shall we write horizontal code now?
TJ
on 10 Sep 12“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”—Martin Fowler
Bryan Sebastian
on 10 Sep 12What
No 000-Main which calls the following…
010-Read 020-Process until end 999-CleanupAh programming when men were men. Of course, I’m joking. I strongly agree that putting some solid thought and effort into naming your methods helps maintenance of an application immensely. Dare I say there may even be some art to it.
Radex
on 10 Sep 12@Austin exactly, that’s my point. I have nowhere as much experience as, say, David, but now that I think about it, indeed my “application” class&method names are much longer and clear than my “framework” stuff.
btw: it seems that my code examples were cut. Here they are again:
[path lineToPoint:NSMakePoint(MaxX(rect) – 10, MinY(rect) + 10) ];
vs.
[path lx: 100 ];
GregT
on 10 Sep 12By the way: anyone else notice that while this ‘rule’ is often, maybe even usually followed in Java, in SQL, it seems to be the polar opposite?
david pasquinelli
on 10 Sep 12what difference does it make if you embed comments in variable names or if you just put in the comments?
how can embedding comments in a variable name convey anything about control the reasoning behind control flow or relationships between variables?
also, i agree that code is for communicating between people. because of that, sometimes a more prosaic name is worse than a conventional name. this is a problem i have sometimes with cocoa.
david pasquinlli
on 10 Sep 12“how can embedding comments in a variable name convey anything about control the reasoning behind control flow or relationships between variables?”
should be: how can embedding comments in a variable name convey anything about the reasoning behind control flow or relationships between variables.
alpav
on 10 Sep 12David, do you consider using def instead of define_python_function or add_integer_to_integer instead of “+” beneficial for code clarity ?
We all know that number of symbols used for operators is limited (!@#$^x%x*) and number of allowed symbols by any specific language is even less, what if I need more operators ? A set of 2 letter names would come to rescue and is essential in making understandable code just like usual operators ,-,=,= only if … you allow me to break your naming rules.
How about this rule: the length of a name should be reverse proportional to frequency of use and proportional to number of names in the namespace where it’s defined.
ploogman
on 10 Sep 12@ DHH “Smalltalk Best Practice Patterns” – did you keep that book? Or did it go the way of YAGNI?
William Payne
on 10 Sep 12My preferences bounce around from short variable names to long variable names – I have not quite made up my mind yet which is better.
I find that when I start in a new application domain, I tend to prefer longer, more descriptive names, but when I have some time under my belt, my preference changes to shorter, more abbreviated names.
I currently use Python quite a bit, and enforce PEP80 compliance on my source documents, which of course limits line length to 80 chars, and forces my hand somewhat towards shorter names.
My fantasy (and perfectly imaginary) development environment would allow variables to have multiple identifiers – so variables can have single-letter symbols (for mathematical equations), short identifiers for normal use, and longer; more descriptive identifiers, with the ability to switch between abbreviated & verbose views.
Radu
on 10 Sep 12Everything in this post is good. Clarity is, for some strange reason, overlooked. But I don’t agree with the fact that clear naming of variables or other language elements can replace comments. Comments should depict in natural language, logic and complexity that, no matter how clear your code is, will be much easier to be understood if it has clear and and dense comments which goes with you through “the story” of what the code does.
Don Schenck
on 10 Sep 12WOW!; I wrote this 21 months ago!
http://xceeda.blogspot.com/2011/01/things-to-remember.html
p8
on 10 Sep 12So do you also have a method called: make_person_an_outside_subscriber_if_NO_accesses_revoked ?
droope
on 10 Sep 12I personally would think that it is best to compromise, and to write comments and medium-length names.
Anders Pearson
on 10 Sep 12I think “verbose vs terse” is a false dichotomy.
Code Complete, by Steve McConnell, discusses the “variable span” metric. Roughly, a variable’s “span” is the number of lines of code between where it is first defined or introduced and where it is last used. The length of variable’s name then, should be roughly proportional to its span. A variable named ‘i’ can be perfectly clear and appropriate if it’s only used on one or two lines, right next to where it was created (likewise, ’_’ can be perfectly clear in the right context), but would be madness for a global variable used across a large swath of the application.
That said, a lot of code would be improved if developers were in the habit of erring on the side of overly verbose rather than the other way around.
Ray Hightower
on 10 Sep 12Great post. I love the long variable names commonly used in Objective-C because (well-chosen) long names make the code easier to follow. Glad to see that others use this approach with Ruby.
John
on 10 Sep 12David, we’re so lucky to have you. Please, talk more about programming more often on SVN.
alpav
on 10 Sep 12Here are my 10 reasons of concise naming: 1) Concise naming not only benefits intellisense, but also helps to avoid dependency on intellisense (useful for generated code). 2) Small names are easier to remember, type and read. 2-3 letter names are easier to remember as one symbol and are great to be used as method names of a class that needs about 20 very frequently used operators. 3) There is so much more to know about functionality, timing and structure besides name, so descriptive name covers only small part of all the information needed to understand code. 4) Code with long names is less readable because structure is hidden behing forest of long names. 5) With long names it’s hard to see typo. For human beings it’s hard to compare 2 similar looking long strings of characters than 2 short strings. 6) There is good reason behind decision of designers of go and python languages to use “def” and “func” instead of “define” and “function” – and this reason is very high frequency of use. 7) Some would argue that it’s helpful to use global search by long name. I agree with that, but with generated code names can be concatenated, so search will not catch those pieces. Though I see it as one good reason of using longer name often caused by imperfection of coding tools. 8) Some elements of microsoft and non-microsoft user interface don’t allow to see long names so 80 characters-like limit is still valid: index names in SQL Query Analyzer, list of project names in beanstalkapp.com, tab title in any browser and so on. I hate when somebody used long descriptive name and I can’t see it because of that. Using 15 character name while seeing only first 7 characters is direct opposite of clarity. 9) It takes effort and skills to invent good short name in such a way that it’s easy to remember and it does not collide with other names and it’s significantly easier to invent good long name, so making long names is often wrongly sold as ability to write good code when in reality it’s the opposite. 10) As Paul Graham quoted Charles Babbage here www.paulgraham.com/power.html “The quantity of meaning compressed into a small space by algebraic signs, is another circumstance that facilitates the reasonings we are accustomed to carry on by their aid.”
self help guide for anxiety
on 11 Sep 12Pretty great post. I simply stumbled upon your blog and wished to say that I have really loved surfing around your weblog posts. In any case I’ll be subscribing in your rss feed and I’m hoping you write again very soon!
Bob
on 11 Sep 12The Church of 80-character Lines isn’t arbitrary: it comes from text terminals having 80 character lines. Sure this isn’t something we have to worry about these days, but some people are set in their ways.
On the other hand, the position you’re arguing IS arbitrary. How clear should function and variable names be? How many words does it take? You might think convert_to_integer() is clear enough, but maybe someone doesn’t know how big an integer is. Perhaps is should be convert_to_number_that_is_16_bytes_wide(). After all, clarity is important!!!!
Speaking of clarity, have you ever seen comments like this?
// add three to x
x += 3;
That comment is useless because anybody who understands the language syntax will know 3 is being added to the value of x. This comment is much better:
// need to add 3 because blah blah blah
x += 3;
Comments express WHY the code exists, and not what it’s doing. As a competent developer you’re expected to figure out what it’s doing. Three months, six months, or a year later and you’ll still know what it’s doing. But you’ll forget why. Overly verbose names will not save you from that.
Also, I refuse to believe if you’re reading code that loads an extension, you can’t understand what “ext” is but you can understand “theExtensionWeAreNowLoading”. Of course I’m assuming you’ll actually read the function and comprehend what it’s doing rather than rely on the names to tell you.
If you feel the compulsive need to overly explain what things are, then go for it. But don’t fool yourself into thinking it’s actually necessary. Dogma is dogma no matter which side of the fence you’re on.
Michael Sica
on 11 Sep 12Those liking this way of thinking might enjoy the book, Code Complete. McConnell spends an entire chapter talking about how to name things!
eekee
on 11 Sep 12A: With my glasses it’s impossible to read very long lines. Short lines are fine.
B: I’ve never seen a long-name system where some of the names were both long and hopelessly obscure, and I don’t even have much experience with long-name languages! I believe you just can’t summarize some concepts in a single English paragraph, or not in one short enough to be acceptable to even the most die-hard long-name fan.
eekee
on 11 Sep 12A: With my glasses it’s impossible to read very long lines. Short lines are fine.
B: I’ve never seen a long-name system where some of the names were both long and hopelessly obscure, and I don’t even have much experience with long-name languages! I believe you just can’t summarize some concepts in a single English paragraph, or not in one short enough to be acceptable to even the most die-hard long-name fan.
Mr. Clarity
on 11 Sep 12from: make_person_an_outside_subscriber_if_all_accesses_revoked to: sync_person_access
What did I lose? Some words. What did I win? Now I have a method that syncs person access, even if in the future that involves more than making it an outsider. Future compatibility win, and less methods win. And less typing win.
from: shift_records_upward_starting_at to: shift_records_at
Programmers know that “shifting” means upward and “unshifting” means downward, so “shift upward” is redundant. So is “starting_at”. “at” communicated start already, or do you plan having also “ending_at”? Honestly, not fantasy land APIs though? Well? Using standard programmer terms win. Less typing win.
from: someone_just_finished_writing to: on_end_writing
Using standard prefix “on” instead of the horribly redundant “someone_just_finished” Someone? Honestly if it’s not “someone” what else could it be? An objective entity? God? “Just”.. Wait, do you have events that fire “a_bit_later_after_someone_finished_writing”? Curious. Usually events fire when events occur. And “end” = “finished”. Standard prefix win. Clarity win. Less typing win.
So what were you saying again :)?
Berserk
on 11 Sep 12Like mr Clarity, the problem I have with make_person_an_outside_subscriber_if_all_accesses_revoked is that the method name contains implementation details. I don’t think that the exact condition should be in the name. Also, more comon method-> shoot for brevity.
Other than that, clarity is good.
ruby flew too
on 11 Sep 12Mr Clarity. YAGNI. Go for clarity, refactor when you need a “sync_access” method.
on_end_writing becomes more difficult to figure out what the method is for – who is finished writing? a person? an overnight job? gaaah…now I have to read through the logic in the method or check the comments.
Very specific naming has the advantage that it tends to force you towards a single responsibility principle.
anyway you can nitpick any code to your own personal preferences.
Dima Q
on 11 Sep 12In short, what you want is an editor that uses comments and/or semantics in autocomplete lookup.
Mr. Clarity
on 11 Sep 12ruby flew too:
I have noticed people use “YAGNI” as an excuse to produce really sloppy APIs. If you can’t tell what “on_end_writing” refers to in a class/module/library, then that class/module/library has become a “god object” – something that has many and arbitrary combination of responsibilities that were just dropped there without regard for the overall project architecture.
So to me this “have overly long method names describing the method’s implementation” is just a thinly veiled excuse for poor API design. API design is hard. It’s not enough to make a method/function just “clear” in itself. It has to reason, rhyme and fit a rhythm within the API you’re creating. Things have to fit together and share a purpose if you selected to put them together. This has vast positive effect on the internals of your project later on too.
This way instead of having to wonder “why on Earth does this method exist” and guess from its name on a one-by-one basis, you see what the person thought when (s)he was designing the entire API.
As for this post, well, it’s just a cult of the extreme over the practical and reasonable to me. Yes, I don’t use too short and abbreviated names. But I also don’t start writing essays in my symbol names, like seems to be the suggestion.
Comments are NOT a code smell. That’s ridiculous. Comments cover a lot more ground than just “this method does this”. They cover behavior, specifics, and the “why does this exist” which sometimes needs to be said. So that one day when the “why” no longer makes sense, you know you can refactor the API, instead of trusting it makes sense, just because you dropped a nice long name on it.
And thus ends my rant ;)
J. B. Rainsberger
on 11 Sep 12Yes. Of course, the natural next step for #make_person_an_outside_subscriber_if_all_accesses_revoked is to extract method #all_accesses_revoked? and perhaps #make_outside_subscriber, which would replace the longer name with two shorter names, anyway.
alpav
on 11 Sep 12I’ve got 2 more reasons of using short names:
11) When thinking about clarity(readability) we have to consider amount of time it takes to understand one unit of functionality instead of one unit of code.
Consider 20 character heavy packed with features regular expression and a 5 pages of C++ code that implements the same thing. I bet that amount of time that it takes to understand C++ code will far exceed amount of time it takes to understand regular expression.
But usually when someone quickly looks at a line of code and finds that takes more than 5 minutes to understand it, he starts complaining that code is unreadable.
Considering clarity/readability per line of code will cause same results as paying per line of code – people will start inserting empty lines between each line considering that as improvement of readability. I’ve seen that thing to happen.
12) Using longer names causes transformation of code structure, making it more bulky and consequently less readable (per unit of functionality of course). Longer name causes lines to split, more lines causes more functions, more functions cause more names to invent, more functions make related pieces of code to be separated, more lines of code cause more files, more files – more folders, more methods – more classes, more classes – more dlls, more dlls – more dll names.
As a result total time it takes to understand one application (or one unit of code) grows – the more it grows the more often people invoke the need to use more descriptive names, so the process is recursive just like with big government – too much spending of characters causes more spending of characters.
Rajesh
on 11 Sep 12Clarity is good but declaring function name like make_person_an_outside_subscriber_if_all_accesses_revoked is insane.
Anonymous Coward
on 11 Sep 12“but declaring function name like make_person_an_outside_subscriber_if_all_accesses_revoked is insane.”
Insane why? Be specific.
Paul d'Aoust
on 11 Sep 12@Austin Schneider, I loved your comment about method names getting shorter as your code improves—I’ve been experiencing the same thing myself, with the number of parameters a method should have. If I have too many boolean flags or optional parameters (or just too many parameters of any sort), it’s to me the same as putting an ‘and’ or an ‘or’ in the method name. Smelly code.
Spaceghost
on 12 Sep 12I felt like Kent Beck’s facebook note “Naming from the outside in” conveyed the idea in very good and consumable way that gave me the ability to buy in easier.
I enjoy the agreement though.
Anonymous Coward
on 12 Sep 12Comments are code smell because they are only for explaining vague variable names. What a novel a philosophy.
Seb
on 12 Sep 12Beauty is about balance : too short is bad ; too long is bad.
Dennis Wong
on 13 Sep 12I’ll call it total BS. What are the comment features in various languages for? Of course, having function names too short like “a()” or “foo()” is not a good idea, but are we going to ditch “stdin” in favor of “the_standard_input”, “strlen()” in favor of “length_of_the_string()”, or “Math.abs()” for “Mathematics.absolute_value()”?
Besides, have you ever been forced to fix some urgent script/program bugs in the data center where no X is available?
I’m not entirely against your idea that a function name should somehow provide a clue to other developers about what it does. However, as Seb has said, it’s all about balance. And the examples given in the new Basecamp code base is just ridiculous.
mr_python
on 14 Sep 12The standard of 80 chars per line is not ‘ridiculous’. Long lines like yours are far harder to read.
Of course, Ruby has very few rules or recommendations which is why I now use a documented / structured language – Python.
This discussion is closed.