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 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.
- 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):
That way, developers can decide to take the default implementation, override the method or combine them (using super.method).
This implementation calls add(size(), e).
- 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...)
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 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
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.
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.
Mm kaimkhani wrote:
Please check your private messages for an important administrative matter
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.