Meaningless Drivel is fun!*
The moose likes IDEs, Version Control and other tools and the fly likes Generating comments in Eclipse Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login

Win a copy of Android Security Essentials Live Lessons this week in the Android forum!
JavaRanch » Java Forums » Engineering » IDEs, Version Control and other tools
Bookmark "Generating comments in Eclipse" Watch "Generating comments in Eclipse" New topic

Generating comments in Eclipse

John Vorwald
Ranch Hand

Joined: Sep 26, 2010
Posts: 139
Where is a "good" comment and code templates for eclipse that can be imported?
Winston Gutkowski

Joined: Mar 17, 2011
Posts: 7552

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
John Vorwald
Ranch Hand

Joined: Sep 26, 2010
Posts: 139
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?
Winston Gutkowski

Joined: Mar 17, 2011
Posts: 7552

John Vorwald wrote:The question I have are: ...

I'm afraid I'm not up enough on comment templates to advise, so I've moved this Thread to a more appropriate forum.

As to documentation "standards", I have only three (other than using proper English, correct spelling, and decent punctuation):
1. Keep it clear.
2. Keep it on point.
3. Keep it current.

Steve Luke

Joined: Jan 28, 2003
Posts: 4168

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.

I agree. Here's the link:
subject: Generating comments in Eclipse
Similar Threads
Is there a plug-in for making plug-in installation easier?
does SWT used for Real word business application?
How to forwards value from Java Servlet variables to Ant variables
How to remove unsed code
To author