38
votes
16answers
6k views

Good idea to put bug numbers in a comment in the beginning of the source file? [closed]

Is it a good practice to put bug numbers in the file itself inside a header comment? The comments would look something like this: MODIFIED (MM/DD/YY) abc 01/21/14 - Bug 17452317 - npe in drill ...
57
votes
13answers
7k views

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()); ...
3
votes
3answers
131 views

Is there a difference between the quotes in `help',``help“, 'help' and ”help"?

Sometimes I find in the source code files comments have quotation marks like these ,notice the ` : `help' ``help" For example, these are comments from GNU cat source code file, cat.c: /* Plain ...
18
votes
10answers
2k views

Are chatty/humorous comments in source code acceptable or unprofessional? [duplicate]

Possible Duplicate: Humor in Documentation Throughout my professional career, I have often relied on chatty or humorous comments in source code (or source control commit messages) to help ...
2
votes
6answers
609 views

Shouldn't we count characters of code and comments instead of lines of code and comments? [closed]

Counting lines of code and comments is sometimes bogus, since most of what we write may be written in one or more lines, depending column count limitations, screen size, style and so forth. Since the ...
1
vote
4answers
158 views

Deciphering foreign code

What is the best strategy to go about understanding some one else's code for a medium sized project, if the code is not well documented and does not adhere to many coding standards?
4
votes
5answers
364 views

What is the right level of granularity for code commenting?

Commenting in code I believe is very important but recently I've been reviewing code that has left me wondering particular this one. //due to lack of confidence with web programming leaving this ...
7
votes
6answers
2k views

Is it necessary to write a javadoc comment for EVERY parameter in a method's signature?

One of the devs on my team believes that it is necessary to write a javadoc comment for EVERY parameter in a method's signature. I do not think this is necessary, and in fact I think it can even be ...
8
votes
11answers
1k views

Version control comments - past or present tense

For version control comments what do other users do/recommend - past or present tense? I.e. Changed x to be y. or Changing x to be y.
17
votes
11answers
1k views

“// …” comments at end of code block after } - good or bad?

I've often seen such comments be used: function foo() { ... } // foo while (...) { ... } // while if (...) { ... } // if and sometimes even as far as if (condition) { ... } // if ...
4
votes
4answers
294 views

Correct alignment when outcommenting code

Suppose I have some code void some_block(void) { some_statement_1(); some_statement_2(); some_statement_3(); } Now I wish to out-comment statement #2, but here I never can find a way ...
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 ...