I need commenting suggestions for Java!

[Kromis]

Okay, so...

I need some help with commenting my Java program. My teacher told me that I should comment better on my programs. Here's what I got:

// Something something something (well, I didn't put exactly that...)

Anyways, that's how I comment my program. Just plain and simple. One person in my Java class uses an asterisk box:

/* ***********************************
* *
*********************************** */

Like that. Now I need to one up him (well, he's a friend but I enjoy some healthy competition! ). Here's what I got for my design:

// _,.-~*'`'*~-.,_,.-~*'`'*~-.,_,.-~*'`'*~-.,_,.-~*'`'*~-.,_,.-~*'`'*~-.,_ Something

So...

Can anyone offer any other suggestions for commenting my program? Something that has a nice visual and attractive.

 

[JustAnAverageGuy]

"comment better" means have more comments, not make them look prettier.

Personally I just use

// This function sorts from highest to lowest

The whole wavey line thing is just outright stupid. then again, I would probably think

//-----------------------------------------------
//
// This function sorts from highest to lowest
//
//-----------------------------------------------

is overkill

- JaAG

 

[imported_Ned Flanders]

// FTW

Although, if you produce a JavaDoc for your program and want commenting in the HTML file you need to use:

/*
* Comment
*/

 

[Stuxnet]

Yeah, skip the 3rd grade girl comment style. Do it like the pros: simple and often.

 

[mundane]

Start practicing javadoc-style of comments. Once you make a program of any decent complexity that someone else has to use, they'll thank you for it.

 

[imported_Ned Flanders]

Hell you'll start thanking yourself. Once I get over 2500+ lines I lose track of what does what :S

 

[kamper]

Originally posted by: Kromis
// _,.-~*'`'*~-.,_,.-~*'`'*~-.,_,.-~*'`'*~-.,_,.-~*'`'*~-.,_,.-~*'`'*~-.,_ Something

Awesome. I tried this and it even made my program run faster! Screw all that stuff about describing how your program works. Pure bloat.

Originally posted by: Ned Flanders
// FTW

Although, if you produce a JavaDoc for your program and want commenting in the HTML file you need to use:

/**
* Comment
*/

Fixed.

Edit: that's kinda hard to see. Note the second '*' on the first line of the comment.

 

[Kromis]

Alright! Thanks for your guys' input!

 

[Stuxnet]

Originally posted by: Ned Flanders
Hell you'll start thanking yourself. Once I get over 2500+ lines I lose track of what does what :S

QFT

I comment my code for myself. I have terrible memory, so if I have to come back to something relatively complex in 3 months, I'm not going to have a clue as to what it's doing.

 

[MrChad]

Javadoc style is the only way to go here.

 

[Kromis]

Hmm...alright, time for a bump!

Can someone show me an example of a Javadoc style commenting? I'm not sure I should use it as that's not the way my teacher told me how to comment things. But hey, I might get extra credit or something!

So...would anybody like to show me an example? I don't have anything at the moment so...just give me an example of random stuff being commented Javadoc style.

Thanks in advance!

 

[imported_Ned Flanders]

Originally posted by: Ned Flanders
// FTW

Although, if you produce a JavaDoc for your program and want commenting in the HTML file you need to use:

/*
* Comment
*/

 

[Kromis]

Originally posted by: Ned Flanders

Originally posted by: Ned Flanders
// FTW

Although, if you produce a JavaDoc for your program and want commenting in the HTML file you need to use:

/*
* Comment
*/

Very well, sir.

 

[Chaotic42]

I date my comments as well. I'm not a full-time programmer, but I've had to hack out a few things here and there for various jobs. Dating the comments allowed me to know what sections may be out of date.

 

[duragezic]

As said, your prof most likely meant you need more comments and/or better comments, not vague or pointless ones ("set x to 5"). And please don't ever use that wavy line thing. The block comment like your friend does is pretty standard for class and function comment blocks. Javadoc is used to comment your classes and methods. Then you run "javadoc Class.java" (there are some arguments you might want to use like -private or whatever) and it creates a nice looking HTML file with your class and method descriptions. It's the same thing that Sun uses for the Java API, which IMO is nice and helpful.

But you would still use

// comment

for short comments inside of methods. I'll use multiple // lines or a /*...*/ if it's a big comment. But a lot of my comments were based on the course style guidelines. Almost all courses have style guidelines, if not, follow the language's standard convention. In my Java classes, my classes required a specific file comment block, specific function/method comment block, etc. But one was an OO design class using Javadoc.

So, an example (note the two asterisks following the slash, this indicates Javadoc, and some editors will syntax highlight the comment differently than a /* block comment):

/**
* Write something meaningful but concise about this class's function.
* @author Your Name
* etc...
*/

For an example of a method's Javadoc comment:
/**
* This method searches an array of integers for a number
* @param x the number to search for
* @param array the array of integers to be searched
* @return True if the number was found in the array, false otherwise
*/

Then when you run javadoc on the .java file, your class and methods are laid out nicely, detailing descriptions, parameters, return types, etc. Some courses require Javadoc, some not, but it's pretty easy to learn and something I would assume to be almost a requirement on a job doing Java. But remember to still use // comments inside of methods, wherever you see fit to explain what is happening, but avoid the obvious and redudant comments!

There is also other parts of Javadoc like using "@exception FileNotFoundException if the file doesn't exist", if the method you are writing can throw an exception.

Anyway, it's been a year or two since I wrote much java or used Javadoc, so the above may not be completely correct , but just search the internet for Java style guidelines (Sun probably has a convention) and Javadoc examples.

 

[beyonddc]

I agree with duragezic.

To make a more professional style comment, you should follow the Javadoc comment standard.

For more information, you can visit "How to Write Doc Comments for the Javadoc Tool".

 

[tfinch2]

LOL, I can't believe the OP.

 

[Kromis]

Originally posted by: tfinch2
LOL, I can't believe the OP.

Yeah, sorry. I'm a n00b at everything!

Originally posted by: beyonddc
I agree with duragezic.

To make a more professional style comment, you should follow the Javadoc comment standard.

For more information, you can visit "How to Write Doc Comments for the Javadoc Tool".

I know I could have used Google to search for it (notice I did not use "Google" as a verb, ) but I feel much more comfortable being taught by ATers

And thank you duragezic for that example!

 

[IHateMyJob2004]

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

java commetns are finely detailed. I think this is the style guide I have linked althoguh I know a PDF exists.

If you get Eclipse to do your code in, it has simple auto formatting for commetns. For example, with the carot at a method, press alt-shift-j. That will auto tmeplate a method comment for you in the standard javadoc manner.