File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
The moose likes Java in General and the fly likes Class level comments Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Java » Java in General
Bookmark "Class level comments" Watch "Class level comments" New topic
Author

Class level comments

Jagdeep Sharma
Ranch Hand

Joined: May 24, 2010
Posts: 121

Hi,

What is the right way of writing of Class level comments in Java. I found several example of them on internet but none of them explaining each term meaning and why to use it at all.

Thanks in advance

David Newton
Author
Rancher

Joined: Sep 29, 2008
Posts: 12617

http://java.sun.com/j2se/javadoc/writingdoccomments/

What, specifically, do you have questions about?
Jagdeep Sharma
Ranch Hand

Joined: May 24, 2010
Posts: 121

David Newton wrote:http://java.sun.com/j2se/javadoc/writingdoccomments/

What, specifically, do you have questions about?



Thanks for your reply!

You given me the link for javadoc tool.
Actually i want to know usage of Java Class Level Comment which we place at the top of class.
Jesper de Jong
Java Cowboy
Saloon Keeper

Joined: Aug 16, 2005
Posts: 14111
    
  16

Jagdeep Sharma wrote:Actually i want to know usage of Java Class Level Comment which we place at the top of class.

The document that David gave a link explains how to write Javadoc comments and gives "best practice" guidelines. This is for Javadoc comments on classes, methods, packages and anywhere else where you can put Javadoc comments.

Obviously, in the Javadoc for a class you'd explain what the class represents. When you then generate the HTML documentation with the Javadoc tool, you'll see what you put in the comments there.

Your question is still a bit vague. What exactly do you want to know? What to write in Javadoc comments for a class? Or how to write it? Or why you would want to document your classes?


Java Beginners FAQ - JavaRanch SCJP FAQ - The Java Tutorial - Java SE 7 API documentation
Scala Notes - My blog about Scala
Jagdeep Sharma
Ranch Hand

Joined: May 24, 2010
Posts: 121

Jesper Young wrote:
Jagdeep Sharma wrote:Actually i want to know usage of Java Class Level Comment which we place at the top of class.

The document that David gave a link explains how to write Javadoc comments and gives "best practice" guidelines. This is for Javadoc comments on classes, methods, packages and anywhere else where you can put Javadoc comments.

Obviously, in the Javadoc for a class you'd explain what the class represents. When you then generate the HTML documentation with the Javadoc tool, you'll see what you put in the comments there.

Your question is still a bit vague. What exactly do you want to know? What to write in Javadoc comments for a class? Or how to write it? Or why you would want to document your classes?


Thanks Jesper.

/*
* Classname
*
* Version information
*
* Date
*
* Copyright notice
*/


Above is the general way for commenting a class.
I just want to know how to write them properly.
Campbell Ritchie
Sheriff

Joined: Oct 13, 2005
Posts: 38363
    
  23
Jagdeep Sharma wrote:/*
* Classname
*
* Version information
*
* Date
*
* Copyright notice
*/


Above is the general way for commenting a class.
No, it isn't. You start with /** for one thing. Also because date etc go after @ tags, and there isn't a @copyright tag shows in the link given earlier, you would have to move the copyright notice before date and version.
Mike Simmons
Ranch Hand

Joined: Mar 05, 2008
Posts: 3007
    
    9
Well, wait a minute. Nowhere in the thread so far has there been any indication that Jagdeep is writing JavaDoc comments. Not in Jagdeep's posts, at least. It seems to have been assumed by most others. But the evidence just isn't there.

News item: Not all comments in Java need to be JavaDoc comments. There are two other types of comments - two different syntaxes that yield the same result: a comment that will not appear in the JavaDoc API, but which will be visible to people browsing the source code. The two syntaxes I refer to are comments that begin with "/*", and comments that begin with "//". These seem to be what this thread is supposed to be about, based on what the original poster has said.
Mike Simmons
Ranch Hand

Joined: Mar 05, 2008
Posts: 3007
    
    9
Having said that... Jagdeep: most of the fields in the example you give are things that I would never include in a comment, unless compelled by my employer. They are at best, redundant, and at worst, misleading (if they accidentally get out of date). Most commonly, they are a waste of time for me to read, and distract from much more important things - like the actual code.

Classname: this should be obvious from the statement that says "public class Foo" right after this. Except I can't see that right away, because someone has filled that space with pointless class-level comments. It's also usually obvious from the name of the source file.

Version information: this information is better represented by your version control system. If you don't know what a version control system is, or don't have one, this is a much bigger problem than how to write class-level comments.

Date: same comment as Version information.

Author: you didn't include this, but a lot of other people do. Same comment as Version information.

Copyright notice: this, in my view, is the only one that might -- might -- actually be useful. Mostly only if your company requires it. OK, fine.

Other stuff: well, this is the only part I care about. What other information (not already represented outside the comments) would another programmer need in order to understand this class? Or even if they don't strictly need it -- what sort of introductory material would help another programmer to understand this class quickly?

Don't write a lot of stuff - no one will read it. Don't write anything that was not already immediately obvious from the name of the class plus the optional "extends" clause. Focus on finding anything non-obvious about the class that another programer might need to know. If there isn't anything non-obvious, don't feel the need to include a class-level comment at all. Save them for the times that your readers actually care.
Jagdeep Sharma
Ranch Hand

Joined: May 24, 2010
Posts: 121

Mike Simmons wrote:Having said that... Jagdeep: most of the fields in the example you give are things that I would never include in a comment, unless compelled by my employer. They are at best, redundant, and at worst, misleading (if they accidentally get out of date). Most commonly, they are a waste of time for me to read, and distract from much more important things - like the actual code.

Classname: this should be obvious from the statement that says "public class Foo" right after this. Except I can't see that right away, because someone has filled that space with pointless class-level comments. It's also usually obvious from the name of the source file.

Version information: this information is better represented by your version control system. If you don't know what a version control system is, or don't have one, this is a much bigger problem than how to write class-level comments.

Date: same comment as Version information.

Author: you didn't include this, but a lot of other people do Same comment as Version information.

Copyright notice: this, in my view, is the only one that might -- might -- actually be useful. Mostly only if your company requires it. OK, fine.

Other stuff: well, this is the only part I care about. What other information (not already represented outside the comments) would another programmer need in order to understand this class? Or even if they don't strictly need it -- what sort of introductory material would help another programmer to understand this class quickly?

Don't write a lot of stuff - no one will read it. Don't write anything that was not already immediately obvious from the name of the class plus the optional "extends" clause. Focus on finding anything non-obvious about the class that another programer might need to know. If there isn't anything non-obvious, don't feel the need to include a class-level comment at all. Save them for the times that your readers actually care.



Thanks Mike

You got me right. I wasn't asking for JavaDoc Comment.
And i really liked your answer. I am using SVN but never tried version kind of thing. Can you please collaborate how to use SVN to see version number.
David Newton
Author
Rancher

Joined: Sep 29, 2008
Posts: 12617

Mike Simmons wrote:Well, wait a minute. Nowhere in the thread so far has there been any indication that Jagdeep is writing JavaDoc comments. Not in Jagdeep's posts, at least. It seems to have been assumed by most others. But the evidence just isn't there.

Comments not wrapped with /** aren't class-level--they're not *anything* level. You can't possibly expect me to (a) believe JavaDoc wasn't a reasonable assumption, and (b) think that the people replying here don't know there are non-JavaDoc comments, and that this needs to be pointed out as a "News item".
Jagdeep Sharma
Ranch Hand

Joined: May 24, 2010
Posts: 121

David Newton wrote:
Mike Simmons wrote:Well, wait a minute. Nowhere in the thread so far has there been any indication that Jagdeep is writing JavaDoc comments. Not in Jagdeep's posts, at least. It seems to have been assumed by most others. But the evidence just isn't there.

Comments not wrapped with /** aren't class-level--they're not *anything* level. You can't possibly expect me to (a) believe JavaDoc wasn't a reasonable assumption, and (b) think that the people replying here don't know there are non-JavaDoc comments, and that this needs to be pointed out as a "News item".



Hey David, Please look at this link http://java.sun.com/docs/codeconv/html/CodeConventions.doc2.html
And see Beginning Comment. They are not started with /**. That's what i was talking about.
David Newton
Author
Rancher

Joined: Sep 29, 2008
Posts: 12617

I understand exactly what you're talking about, *now*. But there's nothing other than convention associating a non-JavaDoc comment with a class, so it's *not* "class-level": it's just there.

And as pointed out, except possibly for the copyright, the rest is noise.
Jesper de Jong
Java Cowboy
Saloon Keeper

Joined: Aug 16, 2005
Posts: 14111
    
  16

Jagdeep Sharma wrote:Hey David, Please look at this link http://java.sun.com/docs/codeconv/html/CodeConventions.doc2.html
And see Beginning Comment. They are not started with /**. That's what i was talking about.

That page gives some good info:
3.1.3 Class and Interface Declarations
The following table describes the parts of a class or interface declaration, in the order that they should appear.

1. Class/interface documentation comment (/**...*/) - See "Documentation Comments" on page 9 for information on what should be in this comment.

...

3. Class/interface implementation comment (/*...*/), if necessary - This comment should contain any class-wide or interface-wide information that wasn't appropriate for the class/interface documentation comment.

So, what more do you want to know exactly?
Mike Simmons
Ranch Hand

Joined: Mar 05, 2008
Posts: 3007
    
    9
David Newton wrote:
Mike Simmons wrote:Well, wait a minute. Nowhere in the thread so far has there been any indication that Jagdeep is writing JavaDoc comments. Not in Jagdeep's posts, at least. It seems to have been assumed by most others. But the evidence just isn't there.

Comments not wrapped with /** aren't class-level--they're not *anything* level. You can't possibly expect me to (a) believe JavaDoc wasn't a reasonable assumption, and (b) think that the people replying here don't know there are non-JavaDoc comments, and that this needs to be pointed out as a "News item".

David - I apologize for my snarky tone above, which was inappropriate. The initial post from Jagdeep was indeed quite ambiguous. Later posts gave better clues about what was meant, but that was after your reply.
David Newton
Author
Rancher

Joined: Sep 29, 2008
Posts: 12617

No problem--wasn't angry :)
Jagdeep Sharma
Ranch Hand

Joined: May 24, 2010
Posts: 121

David Newton wrote:No problem--wasn't angry :)



Be happy guys

We are cool coders. ain't we?
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Class level comments