16
votes
12answers
2k views

Correct comment to put for boolean function arguments that are “false”?

From some open source projects, I gathered the following coding style void someFunction(bool forget); void ourFunction() { someFunction(false /* forget */); } I always have doubt about what ...
5
votes
4answers
294 views
+100

Commenting regular expressions

Are there any common practises for commenting the regular expressions: inline comments referring different part of RegEx or general comment for all expression?
22
votes
8answers
1k 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 ...
10
votes
7answers
785 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 ...
2
votes
4answers
284 views

Linking in code comments (to other unique anchors/comments)

How would you recommend creating "anchors" in code comments, so that during maintenance, developers can easily cross-reference other code comments. I realise that software should be intelligently ...
5
votes
15answers
1k views

What do you think of opening brace comments in source code? [closed]

I have developed a habit of writing comments in my code by putting the comments on the same line as the opening brace, after the brace. I've found that this saves vertical space. It also leaves a hint ...
18
votes
9answers
3k views

Style and recommendations of commenting code

I want to hear from you any advice and experience of writing comments in your code. How do you write them in the most easy and informative way? What habits do you have when commenting parts of code? ...
5
votes
1answer
4k views

Header comment format

I realize that the "header comment" format varies from programmer to programmer, but what would be an example of a "good" header comment?
8
votes
7answers
510 views

Commenting/In-Code Documentation Styles

This might be a stupid question, but it's been in the back of my head for a while and I can't find a decent answer anywhere else. I have a teacher who says we should explicitly list each parameter ...
8
votes
9answers
871 views

What are your thoughts on Periods/Full Stops in code comments?

I saw this asked in the SO Tavern, so I'm posting the question here. I thought it an interesting question. (Of course it doesn't belong on SO, but I think it's OK here.) Do you add periods (or, as ...