Linked Questions

99 votes
34 answers
66k views

"Comments are a code smell" [closed]

A coworker of mine believes that any use of in-code comments (ie, not javadoc style method or class comments) is a code smell. What do you think?
27 votes
6 answers
2k views

Beginner's guide to writing comments?

Is there a definitive guide to writing code comments, aimed at budding developers? Ideally, it would cover when comments should (and should not) be used, and what comments should contain. This answer: ...
Cameron's user avatar
  • 468
0 votes
2 answers
129 views

Should I declare motivation when commenting? [duplicate]

When commenting code, which of the two approaches considered good practice? Explain the content of the code, "translate" it to human - readable language, but not provide any explanation ...
avivgood2's user avatar
  • 117
251 votes
16 answers
49k views

What's wrong with comments that explain complex code?

A lot of people claim that "comments should explain 'why', but not 'how'". Others say that "code should be self-documenting" and comments should be scarce. Robert C. Martin claims that (rephrased to ...
Aviv Cohn's user avatar
  • 21.4k
31 votes
17 answers
4k views

Why would a company develop an atmosphere which discourage code comments? [duplicate]

I was taught in university to write comments for our programs. As I write comments, I feel like I have a better organization and understand the programs better. However, I am in a company where most ...
27 votes
11 answers
27k views

Style and recommendations of commenting code

I want to hear from you any advice and experience of writing comments in your code. How do you write them in the most easy and informative way? What habits do you have when commenting parts of code? ...
kyrylomyr's user avatar
  • 443
4 votes
5 answers
17k views

Best way of writing comments in code [closed]

I was wondering how one should write comments in code. I mean, should a comment be a descriptive of what is done in code, like : //we have got array, now we iterate over it. code to iterate array or ...
rahil008's user avatar
22 votes
6 answers
9k views

Best practices in comment writing and documentation

Commenting nowadays is easier than ever. In Java, there are some nice techniques for linking comments to classes, and Java IDEs are good at making comment shells for you. Languages like Clojure even ...
jayunit100's user avatar
11 votes
7 answers
930 views

Are More Comments Better in High-Turnover Environments?

I was talking with a colleague today. We work on code for two different projects. In my case, I'm the only person working on my code; in her case, multiple people work on the same codebase, including ...
joshin4colours's user avatar
8 votes
11 answers
727 views

What should I put in comments while commiting to the Source Control?

I am a lone developer and maintain a SVN server for source control. So far, I haven't followed anything specific while committing my changes. I was just reviewing my previous commits, and couldn't ...
Devdatta Tengshe's user avatar