aspose file tools*
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
JavaRanch » Java Forums » Engineering » IDEs, Version Control and other tools
Bookmark "Generating comments in Eclipse" Watch "Generating comments in Eclipse" New topic
Author

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
Bartender

Joined: Mar 17, 2011
Posts: 8250
    
  23

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.

Winston

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
Bartender

Joined: Mar 17, 2011
Posts: 8250
    
  23

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.

Winston
Steve Luke
Bartender

Joined: Jan 28, 2003
Posts: 4181
    
  21

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.


Steve
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Generating comments in Eclipse