Linked Questions

56
votes
24answers
5k views

Is writing comments inside methods not a good practice? [duplicate]

A friend told me that writing comments inside methods is not good. He said that we should have comments only for the method definitions(javadocs) but not inside the method body. It seems he read in a ...
45
votes
19answers
3k views

Forcing people to read and understand code instead of using comments, function summaries and debuggers? [duplicate]

I am a young programmer (finished computer science university but still under a year of working in the industry) and I recently got a job working on some C code for a decent size web service. Looking ...
22
votes
8answers
2k views

Should comments say WHY the program is doing what it is doing? (opinion on a dictum by the inventor of Forth) [duplicate]

The often provocative Chuck Moore (inventor of the Forth language) gave the following advice[1]: Use comments sparingly! (I bet that's welcome.) Remember that program you looked through - the ...
2
votes
5answers
985 views

Why should you document code? [duplicate]

Possible Duplicate: “Comments are a code smell” I am a graduate software developer for an insurance company that uses an old COBOL-like language/flat-file record storage system. ...
0
votes
3answers
116 views

Add or leave comment for simple race condition logic? [duplicate]

I'm a huge proponent of removing comments for stuff that should be really clear anyway. Stuff like // remove object from list. A pattern you come across now and than is the preventing of race ...
78
votes
56answers
15k views

Worst coding standard you've ever had to follow? [closed]

Have you ever had to work to coding standards that: Greatly decreased your productivity? Were originally included for good reasons but were kept long after the original concern became irrelevant? ...
160
votes
15answers
26k 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 ...
55
votes
17answers
4k views

How to deal with tautology in comments?

Sometimes I find myself in situations when the part of code that I am writing is (or seems to be) so self-evident that its name would be basically repeated as a comment: class Example { /// ...
22
votes
21answers
8k views

Self Documenting Code Vs. Commented Code

I had a search but didn't find what I was looking for, please feel free to link me if this question has already being asked. Earlier this month this post was made: ...
40
votes
6answers
2k views

“I”, “We”, or Neither in code documentation

I find myself writing (hopefully) helpful comments in code (C++) documentation of the type: The reason we are doing this is... The reason I use "we" instead of "I" is because I do a lot of academic ...
14
votes
7answers
803 views

Is it good to keep the bugfix comments within the code?

My team is using clear-case as the version control. The project which I am working is not started 7-8 years back. During the entire life time of the project we had several releases bug-fixes service ...
11
votes
7answers
803 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 ...

15 30 50 per page