4

Should you use "internal abbreviations/slang" inside comments, that is, abbreviations and slang people outside the project could have trouble understanding, for instance, using something like //NYI instead of //Not Yet Implemented?

There are advantages of this, such as there is less "code" to type (though you could use autocomplete on the abbreviations) and you can read something like NYE faster than something like Not Yet Implemented, assuming you are aware of the abbreviation and its (unabbreviated) meaning.

Myself, I would be careful with this as long as it is not a project on which I for sure will be the only developer.

Improve this question
4
  • 9
    Use whatever you believe to be clearest to whomever is going to pick up the code
    – Phil C
    Apr 11, 2011 at 20:42
  • Agreed with Carnotaurus and if you use abbreviations, could not hurt at top of source file to document those just in case someone pulls up said file 5 years from now and is curious.
    – Chris
    Apr 11, 2011 at 20:52
  • Why the downvote?
    – Anto
    Apr 11, 2011 at 21:28
  • nfi, upvoted to compensate. I think this is a perfectly reasonable question.
    – Rein Henrichs
    Apr 11, 2011 at 21:44

7 Answers 7

Reset to default
21

No, treat comments as part of the code, the code should be clear to anyone who is supposed to read it, so don't use anything where they'd have to guess the meaning. Clarity trumps brevity.

Improve this answer
0
10

No.

Programmers don't type, they communicate. "Less code to type" is not a factor worth considering. Instead, as @Carnotaurus suggests, consider how you can improve the clarity and readability of your code.

Improve this answer
4
  • You downvote me and your justification is this nonsense?
    – Rein Henrichs
    Apr 11, 2011 at 21:40
  • 1
    sorry for that. I deleted my comment, and now I downvote you without any justification.
    – P Shved
    Apr 11, 2011 at 22:18
  • 2
    While I agree with almost everything you said, I am not sure your conclusion is valid. If everyone in the company refers to something by an acronym while speaking--and probably while thinking--about it, it is probably clearer to use the acronym. You should not use an acronym simply for brevity, but you definitely should use it for clarity.
    – Tikhon Jelvis
    Apr 11, 2011 at 23:32
  • Keep in mind that the original question was "Should you use ... abbreviations and slang people outside the project could have trouble understanding?". Remember, that has to include people you haven't hired yet. My answer to "Should you use abbreviations and slang that are clear to everyone who will touch the code?" would have been quite different.
    – Rein Henrichs
    Apr 12, 2011 at 1:02
5

It seems to me that if there is a common abbreviation or slang for an internal resource, like DW for data warehouse, then that should be okay as long as everyone, at least culturally, agrees on the abbreviation.

But outside abbreviations and slang like NYI for Not Yet Implemented fall into the same category like LOL since they have tendency to change and fall in and out of fashion quickly over time. NYI could just as easily be NYS for Not Yet Started or NYR for Not Yet Released.

Improve this answer
4

In my opinion if the abbreviation is well known among project team members it's ok to use it in code comments because even if a new developer is hired he/she will always know what it means from other members.

OTOH, if you are the only developer and it's not your personal project or if you know your team mates do not know what it means, do not use it.

Improve this answer
4
  • 1
    You ever been on a project that was resurrected years after the original developers left the company? Trust me, you want un-abbreviated english.
    – Christopher Mahan
    Apr 11, 2011 at 21:03
  • 1
    I have been but uncommon abbreviations always tend to be in the organization culture or in the mind of key persons. In a "Tribal Memory" as Grady Booch describes it.
    – M.Sameer
    Apr 11, 2011 at 21:05
  • 1
    You do realize Grady Booch described tribal knowledge as part of an argument against relying on it? He argued it should be codified so the new developer doesn't have to walk down the hall to ask a coworker what something means. In this context that means either not using the acronym in the first place, or documenting allowed acronyms for code comments as part of a written coding standard. I know for myself I hate both being the person asking or the person asked about a question so easily avoidable.
    – Karl Bielefeldt
    Apr 12, 2011 at 4:26
  • Grady Booch was talking about architectural decisions that are not documented and only exists in the tribal memory. I still see nothing wrong with relying on tribal memory of the team or the whole organization to store acronyms and abbreviations.
    – M.Sameer
    Apr 12, 2011 at 12:46
3

I would only use abbreviations that are common in the domain. In finance, there are a lot of resources to identify EBITDA. Most people involved in the project even outside the development team would understand it. There's just no advantage and many disadvantages.

I'm not keen on language abbreviations either. It is common to use cn (at least in code samples) as a connection, but I'd like to know a little more about it.

Improve this answer
1

A case in point as to why using abbreviations like this is in your own example. You typo-ed "NYE" when you meant "NYI". So you're telling people about new year's eve, it seems. However if you typo-ed "not yet emplemented" they'd still get the idea, whilst just thinking you can't spell.

Coding is not a race, so I don't think "saving keystrokes" is really a valid consideration. The object of the exercise is to write clean, understandable code, and this extends to any "necessary" comment in said code. Parsing an abbrev. is just that little bit more taxing than reading what it says (which one basically does automatically, without any effort).

Improve this answer
-1

There is only one abbreviation* that can be used in comments :

// TODO :

it is easy to grep and locate.

* Or something similar.

Improve this answer

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