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?
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
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.
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...)
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.
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.
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.
0
