24

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.

8
  • 14
    supercalafragalisticexpialadoshus() because It has meaning, I understand it as a Mary Poppins reference. I would not have understood that from supercala().
    – Alb
    Feb 11, 2011 at 21:39
  • 1
    Possible dup programmers.stackexchange.com/questions/24077/…
    – sdg
    Feb 11, 2011 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, 2011 at 22:00
  • 2
    @Alb: you would have understood it if it used namespaces: MaryPoppins::supercala()
    – rwong
    Feb 12, 2011 at 18:16
  • 2
    I was going to guess repr() = repair().
    – Marcie
    Feb 16, 2011 at 17:18

13 Answers 13

36

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 be using our code, as an API for example, or the person 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 best practice.

4
  • 11
    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, 2011 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, 2011 at 17:58
  • is there anyone who is from OOP background (where most variable and method names are ensured to be elaborate) but finding function names in R very very nonsensible. I was not able to digest at first the single character name c for combine() method . There are many such methods as a part of core R language which has such small names which does not make good sense about their function. Is their any philosophy behind having such names. Are functional non-OOP guys really comfortable with these? or is it just me?
    – Mahesha999
    Aug 17, 2016 at 14:13
  • “Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” -- Martin Fowler, "Refactoring: Improving the Design of Existing Code"
    – aloisdg
    Jan 29, 2019 at 13:03
15

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 its 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 it 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 nightmarish 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.

3
  • 4
    The last point is interesting. I hadn't thought about the clash with potentially desirable identifier names.
    – User
    Feb 17, 2011 at 23:04
  • 3
    That's why namespacing exists -- to avoid clashes. Apr 23, 2015 at 7:01
  • It's not clear to me why Python's len is a global function. It could have just been list.length(). They already have __len__ as a custom overload point, I don't see what value you get in wrapping it as a global function. If length() was an instance method, it's not a global function so you could still write length = list.length() with no keyword clashing
    – Alexander
    Nov 12, 2020 at 13:44
7

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.

4
  • Absolutely agreed. It really irks me to see things like col, cat, and elm instead of column, category, and element. I see no benefit of using abbreviations (or as a coworker put it, "single-syllable variable names"). It saves pretty much no time to type "col" rather than "column," and any time savings will be outweighed by other developers repeatedly having to take an extra second or two to figure out what some abbreviation actually means. Apr 23, 2015 at 6:58
  • @ChadJohnson This doesn't make sense. We use abbreviations all the time in real life where succinctness actually adds clarity. Mr, Ms, lb, in, kg, etc, etc. The trick is to recognize when it adds clarity, and when it adds confusion.
    – Brandin
    Feb 9, 2016 at 13:31
  • @Brandin We do use abbreviations every day, but we use common abbreviations. Constantly abbreviating everything willy nilly, however, is confusing in my opinion. "cat" and "col" are not common everyday abbreviations. Feb 9, 2016 at 19:36
  • Well for cat if you want you can write alias concatenate cat if you find the full word concatenate more clear. However, I'm 100% sure no one does that, so it must be easy enough after the first day that you learn the command.
    – Brandin
    Feb 9, 2016 at 19:47
6

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.

3
  • +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, 2011 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, 2011 at 22:13
  • 2
    @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, 2011 at 8:38
5

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.

4
  • but that's a variable not a method name right? I'm just talking about method names here.
    – Alb
    Feb 11, 2011 at 21:49
  • @Alb: Updated answer.
    – Matt
    Feb 11, 2011 at 21:52
  • +1 for mentioning the case of well-known abbreviations like DB or XML.
    – Alb
    Feb 11, 2011 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. Feb 12, 2011 at 1:59
4

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.

1
  • +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, 2011 at 22:22
3

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/

4
  • 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, 2011 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, 2011 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, 2011 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, 2011 at 8:43
2

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.

2

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.

1
  • As pointed by User and dsimcha, there are very good reasons for some short names.
    – maaartinus
    Apr 28, 2011 at 0:15
0

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.

1
  • +1 for the reference back to the mists of time with clunky teletypes. The root of many sins. Feb 11, 2011 at 23:16
0

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

1
  • In Apple land the last example would be latestWebsiteAccessTime. All times are of type Date which internally is seconds stored as double precision float, so you never specify a unit (except to interface with external data). GetThe is pointless, and you don’t use milliseconds.
    – gnasher729
    Nov 12, 2020 at 13:44
0

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.

3
  • 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, 2011 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. Feb 11, 2011 at 23:18
  • I, for one, find atoi perfectly fine (thanks to Mr. Atoz from that one Star Trek episode). Nov 27, 2018 at 21:40
0

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 :-)

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