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
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
40
votes
13 answers

Comment before or after the relevant code

Assuming a comment won't fit (or can't go) on the line it applies to, should one write the comment before the code or after? Well, wherever future readers will best understand the comment's scope. In other words, wherever most programmers/scripters…
msh210
  • 573
27
votes
9 answers

What is a good way to comment if-else-clauses?

Whenever I'm writing a typical if-else-construct in any language I wonder what would be the best way (in terms of readability and overview) to add comments to it. Especially when commenting the else clause the comments always feel out-of-place for…
acme
  • 579
  • 1
  • 5
  • 9
16
votes
5 answers

Is it OK to put a link to Q&A sites in a program's comments?

In quite some codebase you can see comments stating things like: // Workaround for defect 'xxx', (See bug 1434594 on Sun's bugparade) So I've got a few questions, but they're all related. Is it OK to put link to SO questions in a program's…
Tristan St.
  • 261
15
votes
16 answers

Would a language which doesn't allow comments yield more readable code?

Just out of curiosity, I started wondering whether a language which doesn't allow comments would yield more readable code as you would have be forced to write self-commenting code. Then again, you could write just as bad code as before because you…
gablin
  • 17,407
10
votes
8 answers

Why does everybody write to-do comments in capital letters?

I'm doing the same. When there is something "to-do" in my code, I write //TODO .... But I'm curious to know when this started and if there is a reason for writing "to-dos" in all capital letters?
Mohsen
  • 1,990
9
votes
6 answers

Divisional/Sectional comments, good or bad?

I know the general trend against comments explaining how something works, and how it's a good idea to use them only to explain why you're doing what you're doing, but what about using comments as a means of dividing up the code? Assume you have a…
Tarka
  • 1,588
8
votes
8 answers

Does commentary style affect how readers understand code?

This question has been obsessing me for the past 2 months. A while ago a friend who is a great programmer gave me some example codes, and for the first time I've noticed a unique style of organizing comments. He took some effort to design comments…
Bugster
  • 4,013
  • 8
  • 38
  • 44
7
votes
4 answers

What would be a good way to request comments?

In the project/team I'm working the frequency of comments is a little low. One reason might be that it is not clear to the long-time devs what lines in the code really needs a comment (each part of the project has quite fixed devs). To increase this…
WarpEnterprises
  • 81
6
votes
2 answers

What is the difference (if any) between REM statements and comments?

I have recently come across the term REM statement and wondered, is it synonymous with comment?
geminiCoder
  • 309
  • 2
  • 7
6
votes
6 answers

How much commenting is better for coding?

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. Naturally, programming means that I also have to…
ITguy
  • 171
6
votes
2 answers

What has research shown about the effectiveness of comments?

I have been arguing with a friend about the necessity of comments, and the efficiency of different comment styles. The argument ended quite fast, as we could not find any research - or essay - that support either claim. Has any serious research been…
Adam Matan
  • 180
5
votes
9 answers

Do we need "obvious" Method Documentation information?

I know we have questions about comments in general but I'm specifically wondering about Java Doc style method documentation here. I've been pruning unnecessary comments as I refactor and I've noticed our code has painfully obvious descriptions of…
Ben Brocka
  • 2,751
  • 1
  • 19
  • 30
4
votes
3 answers

Is the following comment clear: "Until contested"

Suppose that you see the following pattern in code: function foo() { ... var someFlag = false; // Until contested for/while/if () { ... // Possibly deeply nested in some non-trivial logic someFlag = true; …
Mark
  • 51
  • 3
3
votes
2 answers

Is it a bad practice to cite URLs as references in comments?

Sometimes I think it's useful to cite a webpage (e.g. Stack Overflow questions) to justify and explain a piece of code. Is this considered bad practice?
Fábio Perez
  • 139
1
2