How do YOU comment a source file?

[MrDeathNote]

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.

Agreed. I comment my code a lot for uni as we tend to work in groups. Also I have a head like a sieve so i tend to forget what i was doing in watever source file i'm looking in, especially if i havent worked on the project in a while. Sure, i can figure out what's happening but whats the point when i can just add a few comment lines and save that time.

[XianForce]

Well at the top of each file I usually do something like:

Code: Select all

Author:

Description:

Then I usually just have some single line comments throughout, where I think I need to explain something.

[Milch]

I'm working with CodeBlocks and a DoxyGen plugin, so I have comments like this in each header for the different functions:

Code: Select all

////////////////////////////////////////////////////////////
///A supercool function
/// \param data - takes a pointer to something
/// \return a pointer to something different
////////////////////////////////////////////////////////////
Bla* Function( char* data );

This is pretty cool for group projects, because they only have to hit a button and they have a supersexy documentation in .html format, or they just switch to the header and read it themselves.

In my the implementation of the function there are just normal comments and ToDo's for the CodeBlocks ToDo Plugin, sometimes a '#warning' so nothing special.

[GroundUpEngine]

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

Agreed, I only do that type of comment on open source or group project, or whatever

Anyways this is what I tend to do ->

Code: Select all

/********************************************************
*  "Filename"
*  "Project Name"
*
*  Created by "Creators Name"
*  Last Updated on "Date" [or] Created on "Date"
*  Copyright "Year Project Begun" by "Creators Name". All rights reserved. [or] "License Info"
*
*********************************************************/

[jasongosen]

I'm using Java and I love comments! The nice Javadoc generator is similar to doxygen in that it looks for special keywords to add descriptions to classes, fields, and methods in the documentation. Plus you never know, down the road you could forget what your mindset was at the time of writing a block of code. Maybe you forgot the precondition for a method or something.

[SD021]

I'm a firm believer in 'good code comments itself'. I write all my code asking myself would someone else be able to read it without comments.

I think uncommented code is miles better than over commented code tbh

That's just me though

[alexdwsn12]

It is depend on the programming language. Which language do you use?. Because different programming language has different style of comments so there is no problem regarding any files,syntax, statements or your own code. It is just comment weather it is source file or etc.

[wearymemory]

I code how Sun... *ahem* ORACLE tells me to.

Click here to see the hidden message (It might contain spoilers)

http://java.sun.com/docs/codeconv/html/ ... C.doc.html

Code: Select all

/*
 * @(#)Blah.java        1.82 99/03/18
 *
 * Copyright (c) 1994-1999 Sun Microsystems, Inc.
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information of Sun
 * Microsystems, Inc. ("Confidential Information").  You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Sun.
 */


package java.blah;

import java.blah.blahdy.BlahBlah;

/**
 * Class description goes here.
 *
 * @version 	1.82 18 Mar 1999
 * @author 	Firstname Lastname
 */
public class Blah extends SomeClass {
    /* A class implementation comment can go here. */

    /** classVar1 documentation comment */
    public static int classVar1;

    /** 
     * classVar2 documentation comment that happens to be
     * more than one line long
     */
    private static Object classVar2;

    /** instanceVar1 documentation comment */
    public Object instanceVar1;

    /** instanceVar2 documentation comment */
    protected int instanceVar2;

    /** instanceVar3 documentation comment */
    private Object[] instanceVar3;

    /** 
     * ...constructor Blah documentation comment...
     */
    public Blah() {
        // ...implementation goes here...
    }

    /**
     * ...method doSomething documentation comment...
     */
    public void doSomething() {
        // ...implementation goes here... 
    }

    /**
     * ...method doSomethingElse documentation comment...
     * @param someParam description
     */
    public void doSomethingElse(Object someParam) {
        // ...implementation goes here... 
    }
}

[Ginto8]

I code how Sun... *ahem* ORACLE tells me to.

Click here to see the hidden message (It might contain spoilers)

http://java.sun.com/docs/codeconv/html/ ... C.doc.html

Code: Select all

/*
 * @(#)Blah.java        1.82 99/03/18
 *
 * Copyright (c) 1994-1999 Sun Microsystems, Inc.
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information of Sun
 * Microsystems, Inc. ("Confidential Information").  You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Sun.
 */


package java.blah;

import java.blah.blahdy.BlahBlah;

/**
 * Class description goes here.
 *
 * @version 	1.82 18 Mar 1999
 * @author 	Firstname Lastname
 */
public class Blah extends SomeClass {
    /* A class implementation comment can go here. */

    /** classVar1 documentation comment */
    public static int classVar1;

    /** 
     * classVar2 documentation comment that happens to be
     * more than one line long
     */
    private static Object classVar2;

    /** instanceVar1 documentation comment */
    public Object instanceVar1;

    /** instanceVar2 documentation comment */
    protected int instanceVar2;

    /** instanceVar3 documentation comment */
    private Object[] instanceVar3;

    /** 
     * ...constructor Blah documentation comment...
     */
    public Blah() {
        // ...implementation goes here...
    }

    /**
     * ...method doSomething documentation comment...
     */
    public void doSomething() {
        // ...implementation goes here... 
    }

    /**
     * ...method doSomethingElse documentation comment...
     * @param someParam description
     */
    public void doSomethingElse(Object someParam) {
        // ...implementation goes here... 
    }
}

god DAMN that's too much commentation. Anyone who needs to comment like that must have absolutely horrid naming conventions

[avansc]

I code how Sun... *ahem* ORACLE tells me to.

Click here to see the hidden message (It might contain spoilers)

http://java.sun.com/docs/codeconv/html/ ... C.doc.html

Code: Select all

/*
 * @(#)Blah.java        1.82 99/03/18
 *
 * Copyright (c) 1994-1999 Sun Microsystems, Inc.
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information of Sun
 * Microsystems, Inc. ("Confidential Information").  You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Sun.
 */


package java.blah;

import java.blah.blahdy.BlahBlah;

/**
 * Class description goes here.
 *
 * @version 	1.82 18 Mar 1999
 * @author 	Firstname Lastname
 */
public class Blah extends SomeClass {
    /* A class implementation comment can go here. */

    /** classVar1 documentation comment */
    public static int classVar1;

    /** 
     * classVar2 documentation comment that happens to be
     * more than one line long
     */
    private static Object classVar2;

    /** instanceVar1 documentation comment */
    public Object instanceVar1;

    /** instanceVar2 documentation comment */
    protected int instanceVar2;

    /** instanceVar3 documentation comment */
    private Object[] instanceVar3;

    /** 
     * ...constructor Blah documentation comment...
     */
    public Blah() {
        // ...implementation goes here...
    }

    /**
     * ...method doSomething documentation comment...
     */
    public void doSomething() {
        // ...implementation goes here... 
    }

    /**
     * ...method doSomethingElse documentation comment...
     * @param someParam description
     */
    public void doSomethingElse(Object someParam) {
        // ...implementation goes here... 
    }
}

god DAMN that's too much commentation. Anyone who needs to comment like that must have absolutely horrid naming conventions

thats for javadoc, its not too much.
how else do you think those lovely html documents get made?

[ismetteren]

I code how Sun... *ahem* ORACLE tells me to.

Click here to see the hidden message (It might contain spoilers)

http://java.sun.com/docs/codeconv/html/ ... C.doc.html

Code: Select all

/*
 * @(#)Blah.java        1.82 99/03/18
 *
 * Copyright (c) 1994-1999 Sun Microsystems, Inc.
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information of Sun
 * Microsystems, Inc. ("Confidential Information").  You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Sun.
 */


package java.blah;

import java.blah.blahdy.BlahBlah;

/**
 * Class description goes here.
 *
 * @version 	1.82 18 Mar 1999
 * @author 	Firstname Lastname
 */
public class Blah extends SomeClass {
    /* A class implementation comment can go here. */

    /** classVar1 documentation comment */
    public static int classVar1;

    /** 
     * classVar2 documentation comment that happens to be
     * more than one line long
     */
    private static Object classVar2;

    /** instanceVar1 documentation comment */
    public Object instanceVar1;

    /** instanceVar2 documentation comment */
    protected int instanceVar2;

    /** instanceVar3 documentation comment */
    private Object[] instanceVar3;

    /** 
     * ...constructor Blah documentation comment...
     */
    public Blah() {
        // ...implementation goes here...
    }

    /**
     * ...method doSomething documentation comment...
     */
    public void doSomething() {
        // ...implementation goes here... 
    }

    /**
     * ...method doSomethingElse documentation comment...
     * @param someParam description
     */
    public void doSomethingElse(Object someParam) {
        // ...implementation goes here... 
    }
}

god DAMN that's too much commentation. Anyone who needs to comment like that must have absolutely horrid naming conventions

Thats javadoc... its meant to be read without reading any code but the method definition.... You should only comment like that if you plan to make documentation using javadoc.