• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

how to write affective comments in java class file?

 
Ranch Hand
Posts: 400
Hibernate Spring Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
Sheriff
Posts: 11343
Mac Safari Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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 Spring Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
Author
Posts: 12617
IntelliJ IDE Ruby
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
Sheriff
Posts: 22783
131
Eclipse IDE Spring VI Editor Chrome Java Windows
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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...)
 
Java Cowboy
Posts: 16084
88
Android Scala IntelliJ IDE Spring Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
Posts: 12617
IntelliJ IDE Ruby
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
Bartender
Posts: 2911
150
Google Web Toolkit Eclipse IDE Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
Posts: 22783
131
Eclipse IDE Spring VI Editor Chrome Java Windows
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
Mac Safari Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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 Spring Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
i usually write the unexpected behavior in comments.
 
Bartender
Posts: 11497
19
Android Google Web Toolkit Mac Eclipse IDE Ubuntu Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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 Spring Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I HAVE REPLIED PLEASE CHECK.
 
David Newton
Author
Posts: 12617
IntelliJ IDE Ruby
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
Bartender
Posts: 11497
19
Android Google Web Toolkit Mac Eclipse IDE Ubuntu Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Mm kaimkhani wrote: I HAVE REPLIED PLEASE CHECK.


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