How “self-documenting” can code be without being annoying? [closed]

Answer 1

I think it's ok to abbreviate when the name would hurt readability or just be redundant.

Example 1: An argument to a method where the type allready conveys all information necessary.

Example 2: A variable that will be use a lot in an obvious way

StringBuilder sb = ...
sb.append(...
sb.append(...
return sb.toString();

Example 3: Idiomatic abbrevations. i,j,k has allready been mentioned. "sb" above is one in our code, and each team probably has a couple more.

Answer 2

Personally, I find verbosity a good thing, but it's easy to be overly verbose too, which is a bad thing. There is a balance, and abbreviations can come into that balance too.

These are my general rules:

• Iterators can be one letter, ie. i, j, k, etc.
• Other one word variables like boolean toggles, what have you are never abbreviated, ie. installing, done, etc.
• Multiple word variables and function names are candidates for abbreviation, but only if they are starting to get rediculously long (say, 20-25+ characters). Intelligent abbreviation is the key here. function => func for instance, but never fun, f, or functi

Answer 3

Aim for shorter rather than longer, but reader understanding should trump laziness to type every single time.

As others have said, variable name length shouldn't obscure logic or algorithm. For example, in arithmetic, we write

( 1 + 5 ) * 3 = 18

rather than

three multiplied by the sum of one and five equals eighteen

because we are trying to draw attention to other things than the clarity of the elements involved in the expression.

I tend to keep variables to one to three words, abbreviating only when I exceed 24 characters or so. The less frequently a variable is used, the more likely I am to feel free to make the variable name long. More frequently used variables I will make shorter.

Answer 4

I suggest taking a minimalist approach. Use a little as possible while ensuring your code stays clear, concise and to the point.

Answer 5

I think that the main problem with abbreviations is that not all the people abbreviates on the same way, so when you work with many people it only can increase the probability of error when coding. For example if you have a constant that can be called SOMETHING_INTERFACE, maybe some developers would abbreviate it as SOMETHING_INTFACE, others as SOMETHING_IFACE or SOMETHING_IF, SMTHING_IFACE...

With only two words you can have at least half a dozen of more or less "logic" possible abbreviations, so I think it's better in the most of the cases to write without abbreviations and with more reasons if you want to have self-docummented code.

Very long names can be annoying sometimes, but can also be abbreviated in very local scopes using auxiliar variables.

Answer 6

When programming you are using the syntax so that humans can read it, the length of the variable names, methods, etc... are really irrevelant.

The more verbose the better usually, with a good development environment you should have code completion anyway, so you can simply hit "add_L"+TAB to finish the method call.