Are short abbreviated method/function names that don't use full words bad practice or a matter of style? [duplicate]

Question

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.

Answer 1

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.

Answer 2

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.

Answer 3

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.

Answer 4

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.

Answer 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.

Answer 6

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.

Answer 7

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/

Answer 8

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.

Answer 9

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.

Answer 10

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.

Answer 11

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

Answer 12

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.

Answer 13

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