Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
8  
Use whatever you believe to be clearest to whomever is going to pick up the code –  Carnotaurus Apr 11 '11 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 '11 at 20:52
    
Why the downvote? –  Anto Apr 11 '11 at 21:28
    
nfi, upvoted to compensate. I think this is a perfectly reasonable question. –  Rein Henrichs Apr 11 '11 at 21:44
add comment

6 Answers

up vote 12 down vote accepted

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.

share|improve this answer
1  
+1 "Clarity trumps bevity." Exactly. –  Oliver Weiler Apr 11 '11 at 21:32
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
    
You downvote me and your justification is this nonsense? –  Rein Henrichs Apr 11 '11 at 21:40
    
sorry for that. I deleted my comment, and now I downvote you without any justification. –  Pavel Shved Apr 11 '11 at 22:18
    
Well, thanks. Sort of. facepalm –  Rein Henrichs Apr 11 '11 at 22:29
1  
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 '11 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 '11 at 1:02
add comment

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.

share|improve this answer
    
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 '11 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 '11 at 21:05
    
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 '11 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 '11 at 12:46
add comment

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.

share|improve this answer
add comment

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

// TODO :

it is easy to grep and locate.

* Or something similar.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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