Linked Questions

66 votes
23 answers

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 ...
53 votes
19 answers

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 ...
31 votes
17 answers

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 ...
24 votes
8 answers

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 one ...
Assad Ebrahim's user avatar
25 votes
6 answers

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 ...
Lilienthal's user avatar
14 votes
11 answers

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 ...
Sungguk Lim's user avatar
6 votes
6 answers

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. ...
ITguy's user avatar
  • 171
4 votes
5 answers

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. The ...
Edwin Tripp's user avatar
76 votes
56 answers

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? ...
251 votes
16 answers

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
184 votes
23 answers

How can I deal with a team member who dislikes making comments in code?

One of my team members consistently avoids making comments in his code. His code is not self-documenting, and other programmers have a difficult time understanding his code. I have asked him ...
91 votes
12 answers

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 ...
Bjorn's user avatar
  • 1,083
56 votes
17 answers

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 { /// <...
25 votes
22 answers

Self-documenting Code vs Commented Code

To summarize the following article: Why You're a Bad PHP Programmer you're a bad programmer if you don't write comments. My personal opinion is that code should be descriptive and mostly not require ...
42 votes
13 answers

Are outdated comments an urban myth?

I constantly see people making the claim that "comments tend to become outdated." The thing is, I think I have seen maybe two or three outdated comments my entire career. Outdated information in ...
Karl Bielefeldt's user avatar

15 30 50 per page