Win a copy of Functional Reactive Programming this week in the Other Languages forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

how to write affective comments in java class file?

 
Minhaj Mehmood
Ranch Hand
Posts: 400
Hibernate Java Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
marc weber
Sheriff
Posts: 11343
Java Mac Safari
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Minhaj Mehmood
Ranch Hand
Posts: 400
Hibernate Java Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 12617
IntelliJ IDE Ruby
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Pie
Posts: 20669
65
Chrome Eclipse IDE Java Windows
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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...)
 
Jesper de Jong
Java Cowboy
Saloon Keeper
Posts: 15492
43
Android IntelliJ IDE Java Scala Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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/
 
David Newton
Author
Rancher
Posts: 12617
IntelliJ IDE Ruby
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Bartender
Posts: 1309
10
Eclipse IDE Google Web Toolkit Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
Rob Spoor
Sheriff
Pie
Posts: 20669
65
Chrome Eclipse IDE Java Windows
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 11343
Java Mac Safari
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 400
Hibernate Java Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
i usually write the unexpected behavior in comments.
 
Maneesh Godbole
Saloon Keeper
Posts: 11185
15
Android Eclipse IDE Google Web Toolkit Java Mac Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Mm kaimkhani wrote:

Please check your private messages for an important administrative matter
 
Minhaj Mehmood
Ranch Hand
Posts: 400
Hibernate Java Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I HAVE REPLIED PLEASE CHECK.
 
David Newton
Author
Rancher
Posts: 12617
IntelliJ IDE Ruby
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 11185
15
Android Eclipse IDE Google Web Toolkit Java Mac Ubuntu
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Mm kaimkhani wrote: I HAVE REPLIED PLEASE CHECK.

Please keep it down
Please check my reply in the PM
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic