57
votes
24answers
7k 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 ...
44
votes
19answers
4k 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 ...
29
votes
17answers
3k 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 ...
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 ...
22
votes
6answers
3k views

Explaining new or uncommon syntax in comments [duplicate]

As per the title, should I be explaining syntax that I use in my code when I have a reasonable expectation that a developer looking at my code in the future will not be familiar with it? Short caveats ...
13
votes
11answers
1k views

Is it efficient to attach a comment on every function? [duplicate]

I moved to this company recently, and my first reaction of the development process leaves me with doubts. Here is where I really doubt the efficiency: Every single function must have Javadoc style ...
5
votes
6answers
386 views

How much commenting is better for coding? [duplicate]

I don't have a formal computer science education, meaning that I did not study computer science topics in a university. However, I work at a programming job and write a reasonable amount of code. ...
3
votes
5answers
2k 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. ...
78
votes
56answers
20k 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? ...
193
votes
16answers
33k 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 ...
71
votes
9answers
9k views

Clean Code comments vs class documentation

I'm having some discussions with my new colleagues regarding commenting. We both like Clean Code, and I'm perfectly fine with the fact that inline code comments should be avoided and that class and ...
54
votes
17answers
4k views

How to deal with tautology in comments? [closed]

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
14k 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: ...
41
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
876 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 ...

15 30 50 per page