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.

Possible Duplicates:
Self Documenting Code Vs. Commented Code

“Comments are a code smell”

Best practices in comment writing and documentation

Is commenting code useful, or just a waste of time?

It seems so trivial but I've partaken in several quite heated discussions on this topic as well as it being a long-standing point of contention between my own learned philosophies and those of our local university.

After reading Bob Martin's Clean Code I chugged the "self commenting code" kool-aid and subsequently flew in the face of everything I was taught in my undergrad years regarding commenting my code.

Does anyone find thoroughly commenting code good for anything other than obligatorily fulfilling your development group's coding standards? I'm very curious to hear everyone's take on this, from both sides. :)

share|improve this question

marked as duplicate by World Engineer, Thomas Owens Feb 27 '12 at 19:56

This question has been asked before and already has an answer. If those answers do not fully address your question, please ask a new question.

Just not with C comments... –  Coder Feb 27 '12 at 20:09

2 Answers 2

up vote 4 down vote accepted

I've generally found comments to be helpful to explain "why", usually by providing context or listing pros and cons of a given approach/algorithm/scheme/etc. The kinds of comments that describe "what" are usually indicative of either redundancy or unclear, poorly reasoned code.

There is an exception to this line of thinking for me, and it occurs in Visual Studio when I'm using XML document comments to provide documentation to clients of my code via Intellisense. Here, I'll add 'redundant' commenting because it's redundant for those reading it -- not those that are seeing a description of the method and parameters pop up in intellisense.

share|improve this answer
comments and code get out of sync over time. Use your code to describe the problem with very descriptive class/method/variable names. –  junky Feb 28 '12 at 18:39

It's good practice. Especially if you're working in a corporate setting. Others need to understand what it is you're trying to do if they're debugging/fixing/

share|improve this answer
I believe that it USED to be good practice 20 years ago. i've been programming for 30 years myself. However now it is frequently a BAD practice as most modern languages are not short on bytes and the idea now is write code that you can read like english, not comments that get stale. They still have a place. Just very rare IMHO. –  junky Feb 28 '12 at 3:31
"Other need to understand" backs this up. The code itself should be more readable to folks who are not familiar with it. –  junky Feb 28 '12 at 3:32

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