«
»

Dn’t Abbrvt

Is req a request or a requisition?

Is res a response, a reservation, a resume, or a result?

Is def a default or a definition?

Is rng a range or a random number generator?

Is v1 version 1 or value 1?

Is e an event, an entity, or an exception?

Is f a file or a float?

Is lst a list or the least value?

Is temp a temporary variable or a temperature reading?

Is rep a representation, a representative, a repetition, or a reputation?

Is tm a time or a trademark? Or even another temporary variable? And if it is a time, is it a timestamp, a time of day, or a duration? (These are three very different things.)

Is admin an administrator, an administrative assistant, or a system administrator?

In context, you can usually figure these things out, but you have to think about them. That’s inefficient. Far better to just spell out what you mean from the get go.

There are a few abbreviations that are so well known and understood that they’re acceptable:

  • max for maximum
  • min for minimum
  • in for InputStream
  • out for OutputStream
  • e or ex for an exception in a catch clause (but nowhere else).
  • num for number, though only when used as prefix as in numTokens, or numHits.

You can use single letter variable names for the occasional quantity that has no meaning other than its type. For example, a string variable can be named s, an int variable i, or a double variable x. However, this should only be used when the program really doesn’t know anything about the nature of the variable other than its type. For example, a method that calculates the cube root of a double may name its argument x; but a method that converts temperature from degrees Fahrenheit to degrees Celsius should name its argument degrees, degreesFahrenheit, or perhaps temperatureFahrenheit.

In addition, there’s nothing at all wrong with using common acronyms that are more recognized than what they stand for: URL, HTML, XML, XSL, etc. However, these are the exceptions, not the rules; and I would still be careful with common abbreviations that mean something else at first glance. EmployeeBO is almost certainly a Business Object, but that wasn’t what you read it as first, was it?

Code should be optimized for reading and comprehension, not for marginally faster typing. You should no more abbreviate names in your code than you do words in your sentences. No1 wnts 2 rd txt wrttn lk ths. 🙂

«
»

This entry was posted on Wednesday, April 28th, 2010 at 5:32 am and is filed under Programming. You can follow any responses to this entry through the Atom feed. Both comments and pings are currently closed.

8 Responses to “Dn’t Abbrvt”

  1. Kieron Says:
    April 28th, 2010 at 6:50 am

    I used to think the same, but sometimes giving things long names makes an algorithm less readable. I think the answer is balance and judgement, rather than completely black or white.

  2. zproxy Says:
    April 28th, 2010 at 7:02 am

    For local variables it is ok to use single letter names, if you keep your method short.

  3. t dugan Says:
    April 30th, 2010 at 10:09 pm

    which is worse?

    float variable1 = constant1 * variable2 * variable3;

    float a = 0.5 * b * h;

    “Dn’t Abbrvt” is an oversimplification of “make names meaningful”

    int tcp_port;

    or

    int transmission_control_protocol_port;

    ?

    Also, proper scoping of values helps…

    float area(Triangle triangle) {return 0.5 * triangle.getBase() * triangle.getHeight();}

  4. ngn Says:
    May 1st, 2010 at 7:31 am

    Here’s my take on the examples:

    > Is def a default or a definition?
    It is a definition. (I come from a Python background.)

    > Is v1 version 1 or value 1?
    Obviously, version 1. What does “value 1” mean anyway?

    > Is e an event, an entity, or an exception?
    Depends on context. Events and exceptions are usually locally-scoped variables, so I think it’s acceptable to name them “e”.

    > Is f a file or a float?
    Could be a function, too.
    I wouldn’t name a float “f”, just because it’s a floating point number. It may be PI for 3.14, r for radius, w for width, dt/kt for debit/credit, or even f because it represents a force, but usually not f because it’s a float.

    > Is temp a temporary variable or a temperature reading?
    Come on…

    > Is tm a time or a trademark? Or even another temporary variable?
    It’s a TransactionManager 🙂 A comment on the line where the variable is declared would solve the mistery (in a statically-typed language even that may be superfluous).

    Things like req/res/lst I never use.

    Abbreviations are, more often than not, obvious from the context. So they can actually improve readability by allowing for concise expression, and letting you focus on the relationships between stuff. On the contrary, fully spelt names constantly remind you about the definitions of stuff. It should be in balance.

    I think this article exaggerates the imbalance which relatively few programmers introduce. Counterexamples exist.

  5. Elliotte Rusty Harold Says:
    May 1st, 2010 at 2:46 pm

    Even when the meaning of abbreviations are obvious from context they still require more mental effort to parse. The only time an abbreviation is appropriate is when the abbreviation is so prevalent that it has effectively replaced the words it stands for in normal speech: URL, HTML, http, etc. And now that I think about it those are all acronyms as much or more than abbreviations. If you wouldn’t say temp instead of temperature or req instead of requisition in normal speech, then you shouldn’t use those abbreviations in code.

  6. James Orenchak Says:
    May 2nd, 2010 at 9:13 am

    I agree with Elliotte. If only commonly used abbreviations, such as URL, TCP or HTML, min or max are used in code, code reviews are much easier. Try to avoid using anything that could be misunderstood.

    @ngn: I’ve seen people call the first value of a list “Value 1”, “Value 2” the second value of a list, etc. The variables named “Value 1”, “Value 2”, “Value 3”, etc. were then assigned values, such as 1, 5 or 256. Just because you think “v1” is automatically “version 1”, doesn’t mean that the person who wrote the code was thinking that way when the code was written. That’s why Elliotte is right when he states that “The only time an abbreviation is appropriate is when the abbreviation is so prevalent that it has effectively replaced the words it stands for in normal speech.”

  7. Sporter Says:
    May 9th, 2010 at 1:22 pm

    @ngn: I’ve seen people call the first value of a list “Value 1″, “Value 2″ the second value of a list, etc. The variables named “Value 1″, “Value 2″, “Value 3″, etc. were then assigned values, such as 1, 5 or 256. Just because you think “v1″ is automatically “version 1″, doesn’t mean that the person who wrote the code was thinking that way when the code was written. That’s why Elliotte is right when he states that “The only time an abbreviation is appropriate is when the abbreviation is so prevalent that it has effectively replaced the words it stands for in normal speech.”
    +1

  8. Thomas Sherer Says:
    May 13th, 2010 at 10:00 am

    Hmmm… Its 2010 and we are still debating this? When called upon to debug an inexperienced programmer’s code, I usually start by renaming abbreviated variables until the code’s problems become obvious. Observers become believers when they see this simple, almost magical transformation. If code cannot be easily be translated into an understandable spoken narrative, then few will ever be able understand it. If another programmer cannot understand some code, then that code can’t be maintained by anyone except its author. Therefore, if maintainabilty is important, code containing lots of abbreviated variables has less value than code with more descriptive variable names.