Page 1 of 2

Comments

Posted: Wed Nov 28, 2007 3:53 pm UTC
by Dingbats
This may be on the far side of pointless, but what the hell :P

I always start my comments with a capital and end with a period, and no space between the comment delimiter and the text. That makes it all look nice and tidy.

Code: Select all

#Like this.

Re: Comments

Posted: Wed Nov 28, 2007 3:55 pm UTC
by crazyjimbo
I can't stand not putting a space between the comment symbol and the beginning of the sentence. But yes, capitals and full punctuation are nice, although I wouldn't bother with a full stop for short comments.

Re: Comments

Posted: Wed Nov 28, 2007 3:58 pm UTC
by pieaholicx
It really depends on the comment, though for styling them I usually put a space between the marker and the comment. My usual stylings:

Code: Select all

# Comment here
; Comment
// Comment
/* Multiple
 * Line
 * Comment
 */


Well, the multiple line doesn't really work, but I put them at the same spacing so the asterisks are a line straight down.

Re: Comments

Posted: Wed Nov 28, 2007 3:59 pm UTC
by Robin S
I have essentially the same protocol for comments as for instant messages: beginning a comment with a capital letter is not necessary; new lines for clauses within a sentence or between sentences are acceptable, in which case appropriate punctuation is not necessary. Otherwise, ordinary grammar, including punctuation.

Re: Comments

Posted: Wed Nov 28, 2007 7:48 pm UTC
by Sana
I tend to always type with proper conventions, and my comments don't break that personal tradition. I always put a space between the comment character and the comment.

Code: Select all

/* My multi-line comments look like this.
­ * I start each subsequent line like this.
­ * I space it so the asterisks line up with the asterisk on the first line. */

Re: Comments

Posted: Wed Nov 28, 2007 7:54 pm UTC
by EvanED
Always a space between the start-of-comment indicator and the first word. Short comments don't have to follow more rules than "be helpful"; longer comments should be in correct English. (Sentences, or at least fragments (like my first "sentence" in this post), capitals, etc.) I shun the comments. I fail to see why

Code: Select all

// Blah blah blah
// blah blah. Blah
// blah.

is not better than

Code: Select all

/* Blah blah blah
 * blah blah. Blah
 * blah.
 */

and I like the "this is continuing a comment" * at the beginning of the lines.

Re: Comments

Posted: Thu Nov 29, 2007 8:09 pm UTC
by Citizen K
I follow the same rules for comments as powerpoint bullets.
If it's a complete sentence or a paragraph, it gets capitalization and punctuation. Otherwise, not. But consistency and parallelism are most critical for legibility.

Re: Comments

Posted: Thu Nov 29, 2007 8:35 pm UTC
by zenten
I tend to write it like this:

Code: Select all

// Here is a single line comment, or at least a few short lines.

/*
Here is a comment that is more like a paragraph or more writing.  Although I'm not doing that here, because I don't have that much to say.
*/

Re: Comments

Posted: Thu Nov 29, 2007 11:44 pm UTC
by Kizyr
If I'm commenting out code, then I'll do something similar as you. Say:

Code: Select all

*data temp;
*   set temp;
*   do i = 1 to 10;
*      output;
*   end;
*run;


If I'm doing descriptive comments, though, I'll always put a space between the comment-mark and the comments, continue comments on the next line with indentation, etc. Punctuation is optional; I'll usually only use it in long comments that need multiple sentences. Say:

Code: Select all

/* Main directory of program */
   %let main_path = C:\Temp;

/* Filenames to read in. For the FY2008 estimation,
   the FY2007 files were used. */
   %let input_files = something1.txt something2.txt;


I'm not picky about how other people do comments, though, so long as it's easy-to-read and consistent. ...and they actually comment to begin with. KF

Re: Comments

Posted: Fri Nov 30, 2007 12:59 am UTC
by Rysto
If I'm commenting out out code, I do:

#if 0
if(something)
....
#endif

Re: Comments

Posted: Fri Nov 30, 2007 1:12 am UTC
by zenten
Rysto wrote:If I'm commenting out out code, I do:

#if 0
if(something)
....
#endif


Ow.

Re: Comments

Posted: Fri Nov 30, 2007 1:21 am UTC
by Rysto
You never have to worry about nested comments when you use #if 0. It really is the best way to go.

Re: Comments

Posted: Fri Nov 30, 2007 1:53 am UTC
by JayDee
wouldn't you still have the same problem if you had nested #endif statments? I'm assuming that'd only happen when you comment out a section of code that already contains a commented section of code, but still.

Oh, and:

Code: Select all

30 REM THIS LINE IS A COMMENT

Re: Comments

Posted: Fri Nov 30, 2007 2:06 am UTC
by Rysto
JayDee wrote:wouldn't you still have the same problem if you had nested #endif statments?

No, #if/#endif nest properly.

Re: Comments

Posted: Fri Nov 30, 2007 3:25 am UTC
by btilly
Rysto wrote:If I'm commenting out out code, I do:

#if 0
if(something)
....
#endif

Thereby leading to much confusion when the next guy finds some of the commented out code, thinks it is live code, finds what they want to change, then tries to fix it.

You are evil, and I'm glad I don't work with you.

About the original question, I use proper English in my comments. Being a decent typist, I don't even have to think about it.

About comments in general, there are a lot of subtle issues on commenting. If you haven't read it, go read what Code Complete says about comments. If you are too lazy to do that, then keep the following facts in mind:

- About 1 line in 10 when initially written has a bug. (This is a general cognitive error rate for people.)
- Bugs in code get fixed.
- Bugs in comments don't.

The result? If comments and code disagree, trust the code. Therefore rather than trying to make code clear by adding comments, you should make code clear to the extent possible by making code clear. That means good variable names, good use of subroutines, etc, etc, etc. There are still things that you should comment, but it will happen less often.

For a discussion of my personal style, see http://www.perlmonks.org/?node_id=65153. (My style has evolved since then, for instance I'm less likely to abbreviate variable names, but what I wrote in that discussion is still largely true.)

Re: Comments

Posted: Fri Nov 30, 2007 3:27 am UTC
by Rysto
Commented-out code of any kind should never make it back into the repository anyway. And any self-respecting IDE recognizes #if 0 and will format the code as a comment anyway.

Re: Comments

Posted: Fri Nov 30, 2007 3:42 am UTC
by btilly
Rysto wrote:Commented-out code of any kind should never make it back into the repository anyway. And any self-respecting IDE recognizes #if 0 and will format the code as a comment anyway.

I've seen plenty of commented out code that made it back to a repository. Why? Because the person who commented it out expects it to be uncommented again sometime. I'll agree that this is often done when it shouldn't be. But sometimes it makes sense.

For instance I might leave in some commented out debugging statements in languages without preprocessors. Some day I'll want to see what queries are hitting the database. Right now I don't.

About syntax highlighting. Yes it is useful and I use it. But I've seen incremental highlighting get confused enough times that I don't want to depend on it.

Re: Comments

Posted: Fri Nov 30, 2007 4:05 am UTC
by Rysto
If a language doesn't have a preprocessor then it doesn't have #if 0, does it?

Re: Comments

Posted: Fri Nov 30, 2007 4:23 am UTC
by btilly
Rysto wrote:If a language doesn't have a preprocessor then it doesn't have #if 0, does it?


It may still have if (0) {...}. (Which frequently is not recognized by syntax highlighting.) Or a multi-line quoting mechanism. Or some other trick that can be abused. (For instance Perl's perldoc mechanism can be used for commenting out blocks of code.)

In all cases it is easy in a decent editor to take a block of code and comment it out in a way that screams out that has been commented out. And then nobody will accidentally think it is live.

Re: Comments

Posted: Fri Nov 30, 2007 4:29 am UTC
by Rysto
There's a big difference between #if 0 and if(0).

Re: Comments

Posted: Fri Nov 30, 2007 4:56 am UTC
by btilly
Rysto wrote:There's a big difference between #if 0 and if(0).


Sure, there are differences. Starting with the fact that one uses the preprocessor, the other doesn't.

However there are a lot of similarities. In particular there is the huge similarity that both mechanisms make a block of code not be executed, which means that they can be used to "comment out" blocks of code. (Only the preprocessor version will comment out blocks of code with illegal constructs though.)

Incidentally if the difference you were thinking of is that one always operates at runtime and the other at compile time, then you're wrong. Depending on the language and compiler, the "runtime" version can get optimized away at compile time.

Re: Comments

Posted: Fri Nov 30, 2007 5:18 am UTC
by Rysto
The biggest difference is that preprocessor directives are not part of the syntax of the language, while if(0) is. A preprocessor directive is far more obvious than if(0).

Re: Comments

Posted: Fri Nov 30, 2007 3:19 pm UTC
by zenten
Rysto wrote:You never have to worry about nested comments when you use #if 0. It really is the best way to go.


Why would I have to worry about nested comments?

Rysto wrote:The biggest difference is that preprocessor directives are not part of the syntax of the language, while if(0) is. A preprocessor directive is far more obvious than if(0).


I would say that neither are terribly obvious.

Re: Comments

Posted: Fri Nov 30, 2007 3:43 pm UTC
by Tei
Compiled code:

Code: Select all


if  (0) {

} else {

}



For optional code, that may one day be readed from a variable, but that now i want to manually adjust, with my hands on the dirty code.

--

Code: Select all

/*  Explanation comment */


Long or one line comment. The official comments, with full logic. Complete phrases.

--

Code: Select all


//TODO: optimize the next call
foo();

bar();//this can break the buffer, but is needed here.



// is the king of small *dirty* comments.

--

Code: Select all


#ifder __BOGUS__


#endif



Proper optional blocks for ...welll optional compiling.

--

Re: Comments

Posted: Fri Nov 30, 2007 4:03 pm UTC
by EvanED
zenten wrote:
Rysto wrote:You never have to worry about nested comments when you use #if 0. It really is the best way to go.


Why would I have to worry about nested comments?

If you are trying to comment out code that has /* */ in it (using /* */ comments), you'll quickly discover why you have to worry about nested comments.

(This is why I [almost] never use /* */ comments; I prefer them to #if 0 for commenting out code as editors are much better about correctly highlighting comments then inactive code. I mean, I've worked on code in VS2005 where we had to turn off the greying out of inactive code because, since we had essentially the equivalent of -D commands elsewhere, VS2005 was greying out the wrong blocks.)

Re: Comments

Posted: Fri Nov 30, 2007 4:15 pm UTC
by Dongorath

Code: Select all

using blah.blah.blah;
#if XLSIO
using Syncfusion.XlsIO;
#endif

[...]

// This function do something (insert explanation here)
protected virtual void myFun(string arg)
{
    // OK, let's the fun begin, I must do this
    // and that...
    // blah blah blah
    /* If I use multiline comment block,
     * I align the stars
     * But I use few of them... Don't know why, though...
     */
    [some code here]

    // The following do something tricky (explanation here)
    // The definition of tricky varies from "it's natural to me, but 80% of my coworkers don't understand" to "eh ! I think that's pretty clever even for me"
    [some "tricky" code]

#if XLSIO
    [code using the Syncfusion library
#endif

    if (false)
    {
        [code that the client don't want today, but I'm pretty sure they'll beg me for it tomorrow]
    }
}


I scarcely use the /* */ comments, and almost never // comments at end of lines. Correct phrases with full punctuation. #if-#endif blocks around blocks that depend on a library that might not be present in the project (I work on 3-layered applications, the first two being supposedly generic, the third is specific to the client).

PS : it's C#.

Re: Comments

Posted: Sun Dec 02, 2007 1:55 am UTC
by Number
if(0) can be used for things other than commenting, such as

Code: Select all

char *p;
switch (n)
{
case 1:
    p = "one";
    if (0)
case 2:
    p = "two";
    if (0)
case 3:
    p = "three";
    printf("%s", p);
    break;
}

You might confuse the person/IDE reading your code. Which, according to the article I took this from, should help promote your job security :D.

Anyway...
// This is a short comment, which is probably < 5 lines long.
// this is really brief

/* Sometimes I line up the stars; it depends on my mood.
*/

During debugging, in-line comments can appear (doSomething(x, /*y*/ z);)

Re: Comments

Posted: Sun Dec 02, 2007 2:48 am UTC
by b.i.o
I use // comments for one or two lines, and /* */ comments for comments longer than that. I also use them for 2 line comments sometimes if I feel it's important enough or it's just easier to have more space.

I leave the first and last lines blank:
/*
* comment goes here
* comment goes here
*/

The stars are lined up always, since emacs does that for me.

Re: Comments

Posted: Sun Dec 02, 2007 9:22 pm UTC
by adlaiff6
poun-difs ear-oh!

Re: Comments

Posted: Mon Dec 03, 2007 12:38 am UTC
by DragonWrangler
With multi line comments, I like them to line up so I do

Code: Select all

/*some words
**more words
**and a few more
*/

Re: Comments

Posted: Mon Dec 03, 2007 2:00 am UTC
by JamesCFraser
I've never written a program in a team, so have never gotten into commenting.
That said, when I use Pascal I write comments of this form:

Code: Select all

if condition
then
  statement
{end if};

Re: Comments

Posted: Tue Dec 04, 2007 12:03 am UTC
by _peterb
Comments are necessary - they should augment code where necessary however most code should self document. Comments are designed to be read by people reading the code - therefore they should not require any form of preprocessing (no image tags) ie Javadoc is bad.

If people want to combine documentation with commenting (which is a good idea), some system that processes natural language ASCII (or unicode) such as markdown should be used.

IMHO

Peter

Re: Comments

Posted: Tue Dec 04, 2007 4:25 am UTC
by OmenPigeon
Shame on all of you. The proper way to comment is, of course,

Code: Select all

""" Oh, man, look at all the awesome things happening in my code.
    You should really read this because it is IMPORTANT. """

The best part is, when you write the comment above a function declaration, you get something like

Code: Select all

""" This is a function.  It does amazing things,
    and you should gaze upon it with wonder and joy,
    for my code is the One True Code, and when you
    finally accept that in your heart, all will be well with
    your immortal soul. """
def foo(bar, baz):
    amazing things are happening here
    just look
    I promise, it's really pretty great

And everything but the 'def' and initial '"""' is indented to the same level, even the name of the function. Le bliss.

Re: Comments

Posted: Tue Dec 04, 2007 6:38 am UTC
by b.i.o
JamesCFraser wrote:I've never written a program in a team, so have never gotten into commenting.
That said, when I use Pascal I write comments of this form:

Code: Select all

if condition
then
  statement
{end if};


I tend to forget exactly what my own code does after a few days if I don't comment it at least a bit...

Re: Comments

Posted: Tue Dec 04, 2007 1:16 pm UTC
by JamesCFraser
Silver2Falcon wrote:
JamesCFraser wrote:I've never written a program in a team, so have never gotten into commenting.
That said, when I use Pascal I write comments of this form:

Code: Select all

if condition
then
  statement
{end if};


I tend to forget exactly what my own code does after a few days if I don't comment it at least a bit...


I prefer not to comment as it gives me experience in seeing how something works just from the code. I can pretty much always see what my own code is doing just reading it.

That said, I do use meaningful variable names

Re: Comments

Posted: Tue Dec 04, 2007 3:08 pm UTC
by enk
JamesCFraser wrote:I prefer not to comment as it gives me experience in seeing how something works just from the code. I can pretty much always see what my own code is doing just reading it.


That can be really difficult, esp. if it's written by someone else.

Consider this program in Casio Basic. I know what it does and have used it a lot, but I simply can't say how it works. But then again, this language only allows one-char variable names :roll:

Spoiler:

Code: Select all

# TITLE:  Approximate Fraction         
# AUTHOR: Karl Ove Hufthammer
# EMAIL:  huftis@bigfoot.com
# WEB:    ?                   
# DATE:   ?
# MAKE:   CASIO
# MODEL:  9850     
# NOTES: 
#
# Just type in a number, and press EXE until you get a accurate enough
# fraction. It's useful with repeating decimal numbers (like 2,715151515...),
# but you can also get good approximations from other numbers (try pi!).

# The program displays the numerator (stored in U), the denominator
# (stored in V), the resulting number, the original number and the
# difference between these two.


@@ Program "APPFRAC"






"Number"?->N
N->B
1->R
Do
  10N->N
  10R->R
LpWhile Frac N<>0
1->S~Y
0->T~X
Do
  N->M
  R->N
  Int (M/N->Q
  M-QN->R
  QY+T->U
  QX+S->V
  U/V->Z
  Locate 2,1,U
  Locate 2,2,V
  Locate 2,3,"-------------"
  Locate 2,4,Z
  Locate 2,5,B
  Locate 2,6,"-------------"
  Locate 2,7,Abs (B-Z
  Do
  LpWhile Getkey<>31
  Y->T
  U->Y
  X->S
  V->X
  LpWhile R>0
Locate 2,7,"Finished"



Re: Comments

Posted: Tue Dec 04, 2007 3:19 pm UTC
by b.i.o
enk wrote:
JamesCFraser wrote:I prefer not to comment as it gives me experience in seeing how something works just from the code. I can pretty much always see what my own code is doing just reading it.


That can be really difficult, esp. if it's written by someone else.

Consider this program in Casio Basic. I know what it does and have used it a lot, but I simply can't say how it works. But then again, this language only allows one-char variable names :roll:

Spoiler:

Code: Select all

# TITLE:  Approximate Fraction         
# AUTHOR: Karl Ove Hufthammer
# EMAIL:  huftis@bigfoot.com
# WEB:    ?                   
# DATE:   ?
# MAKE:   CASIO
# MODEL:  9850     
# NOTES: 
#
# Just type in a number, and press EXE until you get a accurate enough
# fraction. It's useful with repeating decimal numbers (like 2,715151515...),
# but you can also get good approximations from other numbers (try pi!).

# The program displays the numerator (stored in U), the denominator
# (stored in V), the resulting number, the original number and the
# difference between these two.


@@ Program "APPFRAC"






"Number"?->N
N->B
1->R
Do
  10N->N
  10R->R
LpWhile Frac N<>0
1->S~Y
0->T~X
Do
  N->M
  R->N
  Int (M/N->Q
  M-QN->R
  QY+T->U
  QX+S->V
  U/V->Z
  Locate 2,1,U
  Locate 2,2,V
  Locate 2,3,"-------------"
  Locate 2,4,Z
  Locate 2,5,B
  Locate 2,6,"-------------"
  Locate 2,7,Abs (B-Z
  Do
  LpWhile Getkey<>31
  Y->T
  U->Y
  X->S
  V->X
  LpWhile R>0
Locate 2,7,"Finished"




I know what you mean. I simply can't follow anything moderately complicated in TI-Basic. No meaningful variable names, no comments, and only 8 lines on the screen at once.

Re: Comments

Posted: Tue Dec 04, 2007 3:29 pm UTC
by enk
Silver2Falcon wrote:
enk wrote:
JamesCFraser wrote:I prefer not to comment as it gives me experience in seeing how something works just from the code. I can pretty much always see what my own code is doing just reading it.


That can be really difficult, esp. if it's written by someone else.

Consider this program in Casio Basic. I know what it does and have used it a lot, but I simply can't say how it works. But then again, this language only allows one-char variable names :roll:

Spoiler:

Code: Select all

# TITLE:  Approximate Fraction         
# AUTHOR: Karl Ove Hufthammer
# EMAIL:  huftis@bigfoot.com
# WEB:    ?                   
# DATE:   ?
# MAKE:   CASIO
# MODEL:  9850     
# NOTES: 
#
# Just type in a number, and press EXE until you get a accurate enough
# fraction. It's useful with repeating decimal numbers (like 2,715151515...),
# but you can also get good approximations from other numbers (try pi!).

# The program displays the numerator (stored in U), the denominator
# (stored in V), the resulting number, the original number and the
# difference between these two.


@@ Program "APPFRAC"






"Number"?->N
N->B
1->R
Do
  10N->N
  10R->R
LpWhile Frac N<>0
1->S~Y
0->T~X
Do
  N->M
  R->N
  Int (M/N->Q
  M-QN->R
  QY+T->U
  QX+S->V
  U/V->Z
  Locate 2,1,U
  Locate 2,2,V
  Locate 2,3,"-------------"
  Locate 2,4,Z
  Locate 2,5,B
  Locate 2,6,"-------------"
  Locate 2,7,Abs (B-Z
  Do
  LpWhile Getkey<>31
  Y->T
  U->Y
  X->S
  V->X
  LpWhile R>0
Locate 2,7,"Finished"




I know what you mean. I simply can't follow anything moderately complicated in TI-Basic. No meaningful variable names, no comments, and only 8 lines on the screen at once.


Ow.. that beats my Casio fx-9750G PLUS. Only six lines of code visible, each line 21 chars long. But I learned the basics of coding on that machine. Of course, most of my programs and games started as pseudo code on paper :)

Comments, however, are possible on the Casio. Just write it between double quotes:

Code: Select all

?->A
"MAIN LOOP"
Do
...
...
...

Re: Comments

Posted: Wed Dec 05, 2007 5:11 am UTC
by TomBot
btilly wrote:
Rysto wrote:Commented-out code of any kind should never make it back into the repository anyway. And any self-respecting IDE recognizes #if 0 and will format the code as a comment anyway.

I've seen plenty of commented out code that made it back to a repository. Why? Because the person who commented it out expects it to be uncommented again sometime. I'll agree that this is often done when it shouldn't be. But sometimes it makes sense.

For instance I might leave in some commented out debugging statements in languages without preprocessors. Some day I'll want to see what queries are hitting the database. Right now I don't.


If you do that, then when you do want to see the debugging output again, you'll have to turn it on everywhere. A much better idea would be to make a debug function, which you can then simply disable in one place.

In my experience, people who comment out code never explain why. Sometimes it's pretty obvious, like they commented out destructors because they crash. Ugh. I won't say it's a cause, but commented out code is strongly correlated with crappy code.

If you feel the need to put an #if 0, consider #if SOME_DESCRIPTIVE_THING, possibly with a comment, in case you do end up committing it.

Re: Comments

Posted: Wed Dec 05, 2007 5:46 am UTC
by btilly
TomBot wrote:
btilly wrote:
Rysto wrote:Commented-out code of any kind should never make it back into the repository anyway. And any self-respecting IDE recognizes #if 0 and will format the code as a comment anyway.

I've seen plenty of commented out code that made it back to a repository. Why? Because the person who commented it out expects it to be uncommented again sometime. I'll agree that this is often done when it shouldn't be. But sometimes it makes sense.

For instance I might leave in some commented out debugging statements in languages without preprocessors. Some day I'll want to see what queries are hitting the database. Right now I don't.

If you do that, then when you do want to see the debugging output again, you'll have to turn it on everywhere. A much better idea would be to make a debug function, which you can then simply disable in one place.

point.missed();

The point is that occasionally there are some key pieces of information that are useful in debugging lots of different kinds of problems. There are many reasons why I'll want to debug that and only that. I don't want to see a ton of debugging. I just want to see this key piece of information.

The alternative is to use a logger (like Log4J) and just turn logging on/off for a specific logging class. If you're already using a logger, there are lots of reasons to do exactly that. If you're working with existing code, it may be easier to comment out one block rather than try to retrofit a logger on. (Besides, logging imposes overhead. The logging itself is generally lightweight, but runtime stringification of data on the way to calling the logging function can get expensive. Been there, done that.)
TomBot wrote:In my experience, people who comment out code never explain why. Sometimes it's pretty obvious, like they commented out destructors because they crash. Ugh. I won't say it's a cause, but commented out code is strongly correlated with crappy code.

If you feel the need to put an #if 0, consider #if SOME_DESCRIPTIVE_THING, possibly with a comment, in case you do end up committing it.

I'll happily agree that commented out code is a red flag. But red flags are signs of potential problems, not necessarily real ones. And sometimes small amounts of commented out code is OK.