• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

Generating comments in Eclipse

 
Ranch Hand
Posts: 139
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Where is a "good" comment and code templates for eclipse that can be imported?
 
Bartender
Posts: 10780
71
Hibernate Eclipse IDE Ubuntu
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

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
 
John Vorwald
Ranch Hand
Posts: 139
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 10780
71
Hibernate Eclipse IDE Ubuntu
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

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
 
Bartender
Posts: 4179
22
IntelliJ IDE Python Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.

 
Don't get me started about those stupid light bulbs.
reply
    Bookmark Topic Watch Topic
  • New Topic