Software Engineering Stack Exchange
Software Engineering Stack Exchange

Questions tagged [comments]

Questions about writing comments in code.

Questions about comments and documentation in code, including best practices and techniques for commenting and documenting.

199 questions
250
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 my own words) often "comments are apologies for…
Aviv Cohn
  • 21,190
  • 31
  • 118
  • 178
185
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 several times to comment his code, however he just gives…
Md Mahbubur Rahman
  • 4,747
  • 5
  • 32
  • 38
150
votes
17 answers

Coding standard for clarity: comment every line of code?

I've worked in shops that produce life critical software and I've dealt with commenting rules that were meant to keep the code readable and potentially save lives. In my experience though the requirement becomes a brain dead chore to be ticked off…
candied_orange
  • 102,279
  • 24
  • 197
  • 315
99
votes
34 answers

"Comments are a code smell"

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?
Fishtoaster
  • 25,909
  • 15
  • 111
  • 154
98
votes
12 answers

My client wants 25% of comments in my current project, how to react?

junior developer here. I am currently working alone on a web application for a big client of my company. I started last month. The client wants at least 25% of comments in each of its software projects. I checked the code of previous applications…
Robin_
  • 553
  • 1
  • 4
  • 9
98
votes
17 answers

Do TODO comments make sense?

I am working on a fairly big project and got the task to do some translations for it. There were tons of labels that haven't been translated and while I was digging through the code I found this little piece of code //TODO translations This made me…
Ivan Crojach Karačić
  • 547
  • 1
  • 4
  • 12
90
votes
10 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 methods names should be used to express what they…
Bjorn
  • 1,073
  • 1
  • 8
  • 8
89
votes
13 answers

Can commented-out code be valuable documentation?

I wrote the following code: if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); …
Alexis Dufrenoy
  • 1,310
  • 1
  • 11
  • 15
79
votes
13 answers

What are examples of comments that tell you why instead of how or what?

First of all, in this question I'd like to stay away from the polemic on whether source code commenting is good or bad. I'm just trying to understand more clearly what people mean when they talk about comments that tell you WHY, WHAT or HOW. We…
rick
  • 1,945
  • 2
  • 19
  • 16
79
votes
22 answers

How do I convince my fellow devs to WANT to add comments to source code commits?

I know that Subversion (what we're using at work) can be configured to require comments on commits, however I'm not in a position of power to simply turn this on. I know that my reason for commenting my commits is because it is useful, if only as a…
Chris Simmons
  • 351
  • 3
  • 11
78
votes
9 answers

What does XXX mean in a comment?

What do people generally mean whenever you see XXX in a comment. Occasionally, I'll see a comment like this: # XXX - This widget really should frobulate the whatsit Of course, I can tell what the comment means, but what does the XXX generally…
Jason Baker
  • 9,625
  • 8
  • 44
  • 67
72
votes
17 answers

How can I ask my boss (in a polite way) to comment his code?

I am being taught by my boss (I just finished school and he wanted someone with a little programming experience, so he chose me to train me on what that company specializes in) and started working with ASP.NET MVC applications, some HTML and CSS.…
Aidan Quinn
  • 823
  • 1
  • 6
  • 10
67
votes
13 answers

How to avoid comments about one line of code for cleanliness

I'm trying to clean up some of my code using some best practices, and read that comments are almost always a bad idea for future maintainability. I've managed to get rid of most of them by refactoring to methods with good names. However, there are…
Adam B
  • 1,506
  • 2
  • 12
  • 20
64
votes
16 answers

Are first person comments distracting and unprofessional?

I just found myself writing the following comment in some (archaic Visual Basic 6.0) code I was writing: If WindowState <> 1 Then 'The form's not minimized, so we can resize it safely '... End if I'm not sure why I subconsciously use "we"…
dlras2
  • 2,290
  • 2
  • 17
  • 16
64
votes
23 answers

Is writing comments inside methods not a good practice?

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 book that having comments inside the code means…
Srini Kandula
1
2 3
…
13 14