This week's book giveaway is in the OO, Patterns, UML and Refactoring forum. We're giving away four copies of Refactoring for Software Design Smells: Managing Technical Debt and have Girish Suryanarayana, Ganesh Samarthyam & Tushar Sharma on-line! See this thread for details.
John Vorwald wrote:Where is a "good" comment and code templates for eclipse that can be imported?
I don't understand the question.
But just in general, I always use javadoc comments when I'm writing Java code, so you might want to find a good tutorial. And as far as I know, javadoc is built in to Eclipse via the 'export' facility.
Isn't it funny how there's always time and money enough to do it WRONG?
Articles by Winston can be found here
Joined: Sep 26, 2010
I should have been more complete in my question.
Let me start by saying I've been working on one piece of software for the past five years, and now have it reasonably running. I want to "clean" some of the output up, since it seems that in two different locations the solution has been normalized in two different ways.
When I go to bring the two different solutions in line with each other, I can see that the solutions have been normalized different ways. Unfortunately, the way that I want to follow consists of serval classes that have minimal comments. Well, one would think that I would remember since I wrote all the code, but the algorithm is rather difficult to follow, partially due to the complexity, and partially due to the efficiency of the algorithm.
So, I'm going though one file, that contains about five classes to support the algorithm and results presentation. I can see I need to write "good" comments that give meaningful insight into that element. My current eclipse comment templates, under windows/preferences/java/code style/code templates/comments have stuff like file: copyright; type: todo/author; fields: blank comment; constructors: todo/tags; etc.
What I need are examples of good comments. I understand how to write reasonable member function comments: here's what is going to be done; here are the assumptions; here is the algorithm; the results will be. And then throughout the member function document the stages of the algorithm.
I install javadoc, so now when I highlight the class name decleration, and press alt-ctrl-j I get a comment like "The class classname". I would like a more meaningful class template.
The question I have are:
1) What are good standards for comments on the different elements of java?
2) How to implement those standards in eclipse comment templates?
3) And, is there a template file that I can download somewhere?
Writing good documentation is a discipline that is hard to enforce using a template. See this part of the tutorial for some style information. But documentation requires so much more than a template with tags.
My general template would be (ignoring javadoc tags):
Single sentence describing the class
Small paragraph describing the intent of the class
Paragraph describing how the class fits into the package or design.
Series of small paragraphs highlighting the most important methods.
Paragraph on how to use the class, possibly with code examples.