aspose file tools*
The moose likes Beginning Java and the fly likes how to write affective comments in java class file? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Java » Beginning Java
Bookmark "how to write affective comments in java class file?" Watch "how to write affective comments in java class file?" New topic
Author

how to write affective comments in java class file?

Minhaj Mehmood
Ranch Hand

Joined: Jan 22, 2007
Posts: 400

whenever i start to write comments in a class file about functionality(@before the class deceleration/@before the method declaration) i hardly use to manage write 1 or two paragraph
any book recommendation/online resources?

Thanks in advance.


SCJP6 96% | SCWCD5 81% | SCDJWS5 79%
marc weber
Sheriff

Joined: Aug 31, 2004
Posts: 11343

Not that it's perfect (or even consistent), but I use Sun's API documentation as a guide. It's reasonable to assume other developers are accustomed to that.


"We're kind of on the level of crossword puzzle writers... And no one ever goes to them and gives them an award." ~Joe Strummer
sscce.org
Minhaj Mehmood
Ranch Hand

Joined: Jan 22, 2007
Posts: 400

basically those are the rules.
1 post i found while googling it, may be you are also interested to take a look on it=> => http://dkrukovsky.blogspot.com/2005/07/how-to-write-comments.html
David Newton
Author
Rancher

Joined: Sep 29, 2008
Posts: 12617

What specific difficulty are you having? Describe what the method does, if it can't be named in an obvious way. Describe how it does it, if it's not obvious from the implementation. Describe exceptional conditions (if any) if it's not obvious from the implementation.
Rob Spoor
Sheriff

Joined: Oct 27, 2005
Posts: 19696
    
  20

David Newton wrote:Describe how it does it, if it's not obvious from the implementation.

Only if you intend the method to be overwritten. Users of your classes do not care about how a method works, only what it does.

My opinion:
- always write down what the method does. Don't go into to much detail though; for something like an email message, "Sends the message" is more than enough. There is no need to write "Connects to the mail server, logs in, then sends the message".
- if the method is intended to be overwritten, do write down the global implementation details. For example, from AbstractList.add(E):
This implementation calls add(size(), e).
That way, developers can decide to take the default implementation, override the method or combine them (using super.method).
- always write down your preconditions - what values are allowed, which ones aren't. This part can go into the parameter details, or in the exception details. For example:
- don't copy-paste too much. Your comments are easily flawed because you forgot some of the words (I'm doing this too often myself...)


SCJP 1.4 - SCJP 6 - SCWCD 5 - OCEEJBD 6
How To Ask Questions How To Answer Questions
Jesper de Jong
Java Cowboy
Saloon Keeper

Joined: Aug 16, 2005
Posts: 14150
    
  18

Mm kaimkhani wrote:... i hardly use to manage write 1 or two paragraph

Documentation doesn't need to be elaborate to be good.

Sun has some guidelines (including a style guide) for writing Javadoc comments, which might be useful: http://java.sun.com/j2se/javadoc/writingdoccomments/


Java Beginners FAQ - JavaRanch SCJP FAQ - The Java Tutorial - Java SE 7 API documentation
Scala Notes - My blog about Scala
David Newton
Author
Rancher

Joined: Sep 29, 2008
Posts: 12617

Rob Prime wrote:Only if you intend the method to be overwritten. Users of your classes do not care about how a method works, only what it does.

Documentation isn't written just for the consumer, but also the writer, and the maintainer.
salvin francis
Ranch Hand

Joined: Jan 12, 2009
Posts: 928

David Newton wrote:
Rob Prime wrote:Only if you intend the method to be overwritten. Users of your classes do not care about how a method works, only what it does.

Documentation isn't written just for the consumer, but also the writer, and the maintainer.

I didnt think he meant consumer at all

My Website: [Salvin.in] Cool your mind:[Salvin.in/painting] My Sally:[Salvin.in/sally]
Rob Spoor
Sheriff

Joined: Oct 27, 2005
Posts: 19696
    
  20

Actually I was talking about consumers of the library. That does mean other developers. Then again, I was also talking only about (public / protected) Javadoc comments. For your information, I usually write Javadoc comments for everything; from private to public, from fields to nested classes to outer classes.

Comments on how a method work should be contained inside the method, not be part of its API, unless it is a method that is intended to be overridden. Implementation details should in general not be part of the API because it limits you; you can then never change the implementation again without changing the API.
marc weber
Sheriff

Joined: Aug 31, 2004
Posts: 11343

Rob Prime wrote:... Comments on how a method work should be contained inside the method, not be part of its API...

Quite right, and a very good point to keep in mind!

Ideally a method's name should tell the user all they want to know. The API documentation might expand on that (call this when you want _____), but the mechanics of how it's achieved should be left under the hood.
Minhaj Mehmood
Ranch Hand

Joined: Jan 22, 2007
Posts: 400

i usually write the unexpected behavior in comments.
Maneesh Godbole
Saloon Keeper

Joined: Jul 26, 2007
Posts: 10376
    
    8

Mm kaimkhani wrote:

Please check your private messages for an important administrative matter


[How to ask questions] [Donate a pint, save a life!] [Onff-turn it on!]
Minhaj Mehmood
Ranch Hand

Joined: Jan 22, 2007
Posts: 400

I HAVE REPLIED PLEASE CHECK.
David Newton
Author
Rancher

Joined: Sep 29, 2008
Posts: 12617

I'll have to disagree on the complete exclusion of implementation details, quite frankly, for at least two reasons.

1) As a consumer, I may *need* to know about the implementation method, algorithms used, and so on. It might affect how I use the API.

2) I (personally) don't like burying implementation details inside the source code. At best I'd argue this kind of information could go into an implementation guide, but I'd rather not have it plopped in my source code. If the actual implementation is refactored out in a non-public method and the exported API docs only include public methods, fine. But I don't like expository text interspersed with code when it's avoidable.

YMMV.
Maneesh Godbole
Saloon Keeper

Joined: Jul 26, 2007
Posts: 10376
    
    8

Mm kaimkhani wrote: I HAVE REPLIED PLEASE CHECK.

Please keep it down
Please check my reply in the PM
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: how to write affective comments in java class file?