How do YOU comment a source file?

[Bullet Pulse]

I'm just curious to see how you in particular comment the beginning of a file, if you do.

For example: In java class we use the BlueJ default

Code: Select all

/**
  * Write a description of your class here.
  * 
  * @author (your name) 
  * @version (a version number or a date)
  */

And yes this is supposed to be subjective, as I am not looking for the "proper style," just some inspiration on how to do mine.
Thanks

[mv2112]

I'm just curious to see how you in particular comment the beginning of a file, if you do.

For example: In java class we use the BlueJ default

Code: Select all

/**
  * Write a description of your class here.
  * 
  * @author (your name) 
  * @version (a version number or a date)
  */

And yes this is supposed to be subjective, as I am not looking for the "proper style," just some inspiration on how to do mine.
Thanks

I don't.

[Ginto8]

I don't.

That might explain why it sucks
But as for me I only comment things that I need to. I try to name my functions intuitively, so that someone can look and say "Oh, so THAT's what that does!" without even having to look at the source of it. If there are little if something doesn't behave as one might expect at first glance, I'll add a comment. Other than that, I don't really comment, though I try to make my code readable. I'll probably have to go back and comment everything eventually, but when I actually code something I have to have an intimate knowledge of how most of the stuff works anyway, so I don't feel the need for them until I actually stop CODING and start USING.

[davidthefat]

I try to name every thing right so there will be no need for comments, usually never use them

[dandymcgee]

Block comments are a nuisance. Rather than long, draw out walls of text I tend to comment only things that need explaining and in as few words as possible.

[eatcomics]

I like to make the most pointless comments, then see how long it takes me to finally get annoyed and remove them

like so:

Code: Select all

int x; //creates a variable called x
int y; //creates a variable similar to x, but not exactly the same
//this function here takes some parameters, then it does things with them
bool Take180DivBy2();
//if I had a cat, I would probably be feeding it right now

keeps me on my toes

[dandymcgee]

I like to make the most pointless comments, then see how long it takes me to finally get annoyed and remove them

like so:

Code: Select all

int x; //creates a variable called x
int y; //creates a variable similar to x, but not exactly the same
//this function here takes some parameters, then it does things with them
bool Take180DivBy2();
//if I had a cat, I would probably be feeding it right now

keeps me on my toes

Lol. When I was working on my Visual Basic CS project in high school I had to find some way to prevent myself from committing suicide, so I starting naming variables the most ridiculous things I could think of:

Code: Select all

string PopTheBubbleWrap( int peanutButter )
{
    string clouds;
    if( peanutButter < 5 ){
        clouds += "The fan spins on.";
    }else if( peanutButter >= 5 ){
        clouds += "Grow into butterflies caterpillars will.";
    }

    for( int superGlue = 0; superGlue < peanutButter; superGlue++ ){
        clouds += superGlue + " bottles of beer on the wall.";
    }

    return clouds;
}

Yea.. I don't know.

[X Abstract X]

I don't use many comments at all. I try to name things as descriptively as possible, even if it results in a really long name. If I have a complex algorithm I'll comment in a description of what it does, or if I hack something together I'll explain what it does and add a reminder to fix it later.

Code: Select all

string PopTheBubbleWrap( int peanutButter )
{
    string clouds;
    if( peanutButter < 5 ){
        clouds += "The fan spins on.";
    }else if( peanutButter >= 5 ){
        clouds += "Grow into butterflies caterpillars will.";
    }

    for( int superGlue = 0; superGlue < peanutButter; superGlue++ ){
        clouds += superGlue + " bottles of beer on the wall.";
    }

    return clouds;
}

Ugh, somewhat reminds me of my highschool CS class where kids would purposely name things with a misspelling. Instead of naming a variable "length" they would name it "longht" or something rediculous lol.

[dandymcgee]

Ugh, somewhat reminds me of my highschool CS class where kids would purposely name things with a misspelling. Instead of naming a variable "length" they would name it "longht" or something rediculous lol.

That just impedes progress later when you can't figure out why your variables aren't declared. BTW I was the sole programmer, I would never consider this on a group project.

[Falco Girgis]

I don't. From the class name, the function names, and variable names, the purpose of the class should be obvious.

When I'm coding, I find that wading through a bunch of fluff documentation impedes progress. The only thing that I really ever comment is ugly ass low level C/assembly functions or complex math.

I also hate header comments. I would only ever add that stuff to a finished open source project just so people can't steal my work...

Class diagrams and uml diagrams are a much more efficient and informative way to have a right brained look at your code...

[eatcomics]

In all reality I do what you guys do, I make sure the functions and classes are named according to what they are, that way 1) I always know what they do and 2) When I call that function its easier to remember the name

I only comment at the beginning of my main file that says what the program is and who coded it and or reminders of what I need to do...
or if I have some kind of algorithm or something that's not obvious

[Live-Dimension]

I only comment stuff thats not obvious, and 'blocks' of code in long functions to help split it up, unless it's something that I think should need it, like opening/saving in your specific file format. Generally I don't do it that much.

I only write comments with //, this frees me up to use /* */ for debugging purposes.

[Bakkon]

How about an example of comments that I hate?

Code: Select all

/* this function computes something */
int computeStuff(int n) { ... }

People using block comments for a single line pisses me off. Then when you want to comment out a huge chunk of code with /* */ it closes at the end of the function comment instead of where you want.

[cndr]

I usually comment most of my code, mainly so I quickly find what I'm looking for. When I'm testing out my programs at the top of each file I usually put what the known issues are with the program, and ideas on how to fix them, I also write what the last thing I was working on, in case I take a couple days off of programming.

[avansc]

I dont comment shit, its really bad.

Here are a few reasons i suggest commenting a lot.

Getting into the habit even if you dont need it at the time is a good idea, for the fact that alot of large project require it, especially if you work for a decent place.

Keeping source well commented to a certain style makes producing documentation easy, doxygen, javadoc and all those kinda things.

People forget shit, i dont care how smart you think you are, you will oneday look at a simple loop or what not and go, "WTF am i doing here". Im not saying you cant figure it out, but comments make it alot easier.

and lastly, if you are not the only person that will work with the code. or even if someone just calls your code, they can reference the documentation you specifically wrote.