Page 2 of 2
Re: How do YOU comment a source file?
Posted: Mon May 24, 2010 4:00 am
by MrDeathNote
avansc wrote: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.
Re: How do YOU comment a source file?
Posted: Mon May 24, 2010 8:38 am
by XianForce
Well at the top of each file I usually do something like:
Then I usually just have some single line comments throughout, where I think I need to explain something.
Re: How do YOU comment a source file?
Posted: Mon May 24, 2010 3:06 pm
by 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.
Re: How do YOU comment a source file?
Posted: Mon May 24, 2010 3:30 pm
by GroundUpEngine
GyroVorbis wrote: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"
*
*********************************************************/
Re: How do YOU comment a source file?
Posted: Fri Jun 04, 2010 1:24 pm
by 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.
Re: How do YOU comment a source file?
Posted: Sat Jun 05, 2010 11:33 am
by 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
Re: How do YOU comment a source file?
Posted: Tue Jun 22, 2010 7:58 am
by 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.
Re: How do YOU comment a source file?
Posted: Sun Jun 27, 2010 11:18 pm
by 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.htmlCode: 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...
}
}
Re: How do YOU comment a source file?
Posted: Mon Jun 28, 2010 8:30 am
by Ginto8
wearymemory wrote: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.htmlCode: 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
Re: How do YOU comment a source file?
Posted: Mon Jun 28, 2010 8:36 am
by avansc
Ginto8 wrote:wearymemory wrote: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.htmlCode: 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?
Re: How do YOU comment a source file?
Posted: Mon Jun 28, 2010 10:08 am
by ismetteren
Ginto8 wrote:wearymemory wrote: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.htmlCode: 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.