Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Is there nowadays any case for brevity over clarity with method names?

Tonight I came across the Python method repr() which seems like a bad name for a method to me. It's not an English word. It apparently is an abbreviation of 'representation' and even if you can deduce that, it still doesn't tell you what the method does.

A good method name is subjective to a certain degree, but I had assumed that modern best practices agreed that names should be at least full words and descriptive enough to reveal enough about the method that you would easily find one when looking for it. Method names made from words help let your code read like English.

repr() seems to have no advantages as a name other than being short and IDE auto-complete makes this a non-issue. An additional reason given in an answer is that python names are brief so that you can do many things on one line. Surely the better way is to just extract the many things to their own function, and repeat until lines are not too long.

Are these just a hangover from the unix way of doing things? Commands with names like ls, rm, ps and du (if you could call those names) were hard to find and hard to remember. I know that the everyday usage of commands such as these is different than methods in code so the matter of whether those are bad names is a different matter.

share|improve this question
    
supercalafragalisticexpialadoshus() vs supercala() ? –  TheLQ Feb 11 '11 at 21:38
10  
supercalafragalisticexpialadoshus() because It has meaning, I understand it as a Mary Poppins reference. I would not have understood that from supercala(). –  Alb Feb 11 '11 at 21:39
    
Possible dup programmers.stackexchange.com/questions/24077/… –  sdg Feb 11 '11 at 21:54
1  
@sdg it is on the same topic but my question is specifically about methods and functions not identifiers. You typically browse APIs by methods not identifiers, so I believe they are distinct cases. –  Alb Feb 11 '11 at 22:00
1  
long and descriptive doesn't necessarily mean easier to grok. e.g. super_cala_fraga_listic_expi_ala_doshus or superCalaFragaListicExpiAlaDoshus vs supercalafragalisticexpialadoshus. I understand it's one word, but reading it all lowercase "hurts" my eyes –  frogstarr78 Feb 12 '11 at 3:18
show 2 more comments

13 Answers

up vote 14 down vote accepted

I heard a great quote on this once, something along the lines of:

Code is written to be read by humans, not computers

If computers were all we cared about we would still be writing assembler, or 1s and 0s for that matter. We have to consider the people who will using our code, as an API for example, or the guy who comes after us and maintains our code. So, unless the language we are using prohibits it, meaningful, real word method and variable names should be considered a good practice.

share|improve this answer
4  
Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. ~Martin Golding –  Chris Nava Feb 12 '11 at 5:47
    
I forgot that quote. That is great! I think we have all played the role of the "violent psychopath" at least once. ;-) –  TheZenker Feb 12 '11 at 17:58
add comment

I follow the Microsoft Framework Design Guidelines (enforced via FxCop) on variable and method names which basically say that it is bad practice to use abbreviated names or acronyms. However, I think some discretion is needed. If the acronym is well known, then it should be fine. Also for things such as loops abbreviations are fine, such as:

For Each fi As FileInfo in FileInfoArray
Next 

So for modern imperative languages, I think it would be considered bad practice to abbreviate names.

Update:

Sorry, I misread your example. The same principle still applies to method names. I would only abbreviate if the acronym is well known (such as GetCSVFile(), OpenDBConnection(), etc.). In these cases pretty much any programmer would know what CSV or DB stand for. However, I would not use OpenDBConn, OpnDBCn, or GetCSVFl. Again discretion and human readability is key.

share|improve this answer
    
but that's a variable not a method name right? I'm just talking about method names here. –  Alb Feb 11 '11 at 21:49
    
@Alb: Updated answer. –  Matt Feb 11 '11 at 21:52
    
+1 for mentioning the case of well-known abbreviations like DB or XML. –  Alb Feb 11 '11 at 22:17
    
@Alb, I would say this applies equally to variable and method names. You (the programmer) should be able to understand what the variable/method is by the name alone. The general accepted practice (as I understand it) is to only use commonly accepted abbreviations and acronyms (and this is the important part) that are in common use in the application domain. –  Ken Henderson Feb 12 '11 at 1:59
add comment

I very much agree with. If I am looking at a new code base, long descriptive methods name, class names, etc are very much appreciated.

share|improve this answer
add comment

IMHO the optimal verboseness of a method/variable name should be directly proportional to the size of its scope and inversely proportional to how frequently it's used. If a variable/method is used N times in a program, the cost of memorizing what some cryptic name actually does has O(1) overhead but a large constant. The cost of typing, reading and wasting screen real estate on the longer, more verbose name each time is O(N) but with a smaller constant. If a variable/method has a large scope or is public/global, then the chances that you're going to have to understand it and pay the O(1) overhead to modify/understand whatever part of the code you're maintaining are high, arguing for a more verbose name. If its scope is 10 lines, only the person who maintains those 10 lines needs to understand it, arguing for a terser name.

This means that very frequently used standard library functions (like repr, str, list, etc.) should have terse names.

share|improve this answer
    
+1 - typing a four character function name is much easier than typing fourteen. Especially if you're trying to code as you think, typing "representation" in full requires much more effort. –  TZHX Feb 11 '11 at 21:59
    
@TZHX having to type method names or remember them is becoming a thing of the past. Invoke intellisense and it's more important that you can quickly identify the method you need from a list, not that it has a short name. But maybe you do not use a good IDE, or such an IDE does not yet exist for your language? –  Alb Feb 11 '11 at 22:13
1  
@Alb - I'm not sure you understand the point of "scripting" languages then. Quickly being able to throw something together on a command line. And I'm not sure intellisense works with even Iron Python - though I write my python in notepad++ or nano, rather than an IDE. Even when using languages which support intellisense (C++), I find it's much more productive to remember the name of what you want to do, than wait for intellisense to catch up with you. On large projects (say, more than half a million LOC), intellisense becomes very slow - and pre-vs2010 didn't work at all! –  TZHX Feb 12 '11 at 8:38
add comment

I would really love for the guys at the top to get massive amounts of upvotes. That way, at least, I get some assurance that the global community will, in general, appreciate when I write a 35 character method name that documents it's meaning and intention, without necessarily ever having to look up the docs or other code annotations. I hope that we can also agree that ~80 character test case method names aren't bad too, so next time I don't have to look up the test case to figure out why something went wrong.

On the flipside, I prefer when the language built-ins are terse. Reasoning? The language core is something that is so well known to you and me both that it's unambiguous. I can agree that people who are just familiarizing themselves might not understand repr(), dir(), getattr() off the bat, but most modern languages have a very small global footprint that it would take you a mere hour to thoroughly go through all the basic types and functions provided.

I guess there was another incentive to that. You don't want to block developers from writing obvious natural references to something they're working with. Imagine if len() was written as length(), you could never write length = ... from fear of overwriting the global reference in your closure. I'm sure there are people dealing with problems where representation = ... is a sane call.

In a more nightmareish scenario, imagine if result was a reserved keyword or global. Why... I'd cry for an outright hanging of whoever came up with that idea.

share|improve this answer
    
The last point is interesting. I hadn't thought about the clash with potentially desirable identifier names. –  User Feb 17 '11 at 23:04
add comment

In the not-so-distant past, people developed on systems with a limited and set number of characters available on the screen. In legacy systems, this is still the case. It is a feature of many, many coding standards (including the official Python PEPs) that lines shouldn't be over a certain number of characters.

Verbose and long method names make this difficult. When you're only allowed 79 characters on a line, and 8 to 12 of those could conceivably be whitespace in Python, then having a 4 rather than thirteen character name makes a difference.

Relevant PEP - http://www.python.org/dev/peps/pep-0008/

share|improve this answer
2  
if you have 79 per line and 12 are whitespace you still have 55 chars left after a 13 length method name. If you''re calling that many methods per line isn't it a case for refactoring to methods instead of renaming the methods to less descriptive names? –  Alb Feb 11 '11 at 21:48
1  
well, possibly. but most of the standard library functions are meant to be concise, so you can do several things on one line. this is one of the selling points of python - that you don't need to go through half a dozen lines to print out the string representation of elements in a list. –  TZHX Feb 11 '11 at 21:53
    
By the way the first piece of sample code in that link is quite horrible. If having to mentally decipher if statements like that is the cost of brevity I'll take more code lines any day. –  Alb Feb 11 '11 at 22:15
    
Let's just go tell Guido, the inventor of the python language, that his python style is terrible then. Righto. Though as someone who works with python every day, I don't have any trouble understanding the logic in that sample. Yes, there's a lot of ands - but it's hardly complex. –  TZHX Feb 12 '11 at 8:43
add comment

Autocomplete usually doesn't work well in dynamic languages, so having short names for things you need often makes some sense. That said, I prefer readable, i.e. long names in most cases.

share|improve this answer
add comment

I agree with you about names. One of my favorite maxims is "Favor read time convenience over write time convenience" which basically means you are reading a piece of code much more often than you are writing that piece of code, so make it as readable as possible without regard to the "inconvenience" of typing a long name. I tend to write long method names. (e.g. for the comment above about supercalafragalisticexpialadoshus() vs supercala() I would most likely choose the former.)

The only thing I would say though, is because repr is a built-in function it almost takes on the status of a keyword. There is a small limited set of built-in functions. You could make the same argument about keywords, e.g what does "if" or "for" mean? We accept abbreviated words/expressions as keywords so we should extend that acceptance to built-ins.

share|improve this answer
    
+1 for the maxim. "if" and "for" although short, are complete and appropriate words e.g. the line of code: `if( total.equals(10) ) reads like English. –  Alb Feb 11 '11 at 22:22
add comment

The old Unix command names tend to be short and cryptic because they were very often typed on a Teletype or some other slow terminal. Having to type an extra five or six letters frequently could take noticeable amounts of time.

Currently, I'm typing this on the console of a computer with gigabit Ethernet with high-speed connections to the Internet, so I write meaningful variable names. Unless you've not upgraded to a 1200 baud modem or better, do likewise.

share|improve this answer
    
+1 for the reference back to the mists of time with clunky teletypes. The root of many sins. –  quickly_now Feb 11 '11 at 23:16
add comment

Frankly, repr() is not a sign for panic. Imagine dealing with function names like mds_rcv_scv_ckb_sync(), now this is a extrasensory training. The nightmare comes when the code is not documented. There's no information about what function does. While I'm not fond of such encrypted definitions, I still have to write code using them. With today's tools, like code completion, cross-referencing, the readability is somewhat easier, given that the methods are documented. You can just Ctrl+Space and see the function list together with corresponding documentation.
On the other hand, functions like GetTheLatestWebSiteAccessTimeInMilliseconds() is another extremal case.
I like Microsoft's naming guidelines they use in .NET

share|improve this answer
add comment

Precedent or tradition. Atoi for example is a rather classic function that is an abbreviation that I suspect a lot of people just absorb as part of an older language like C. It would be an argument that I could see some people making though in newer languages this shouldn't be as big of an issue. Malloc would be another one of those esoteric functions if someone wanted another example. Most of this has been replaced with newer languages and tools, but there may be some old school people that cling to things like Hungarian notation which may cause nightmares given how ugly it can make things in modern tools. I never said this was a good argument, just that I could picture some people putting it forth.

share|improve this answer
2  
Maybe it's just me, but the term 'legacy code' reminds me of long functions, no unit tests, esoteric short names (atoi is a great example btw), gotos etc... all precedents which have been replaced by better practices. –  Alb Feb 11 '11 at 21:42
    
I find the term "legacy" anything to be quite offensive. It's not helpful apart from being a derogatory term, and is used to dismiss any practice that's more than about 2 years old. The world is full of older systems, and practices that suit those systems. –  quickly_now Feb 11 '11 at 23:18
add comment

Short method names mattered in the time of 128k or less of memory where literally every byte counted. Today, there absolutely no reason to use cryptic abbreviated names for methods when longer more descriptive names do not have any practical costs.

share|improve this answer
    
As pointed by User and dsimcha, there are very good reasons for some short names. –  maaartinus Apr 28 '11 at 0:15
add comment

I don't want the comment to be part of the name thanks. Concise is good!

Dictionaries are concise. To use one fully, you have to read about some of their specialist abbreviations for things that are used many times. Similarly, seeing a variable called 'incrementer' in source would be worse than just using 'i'.

Many windows and Java library names are far too long. If you want to know what something does then read the code around it - don't expect to be told - correctly, enough by its name.

A lot of Microsoft and java code is made impenetrable as you are confronted by a complex web of source made worse by the over-long identifiers.

At least Microsoft had the good sense to go for a short, catchy, name for the linq feature rather than languageIntegratedQuery :-)

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.