Eclipse IDE is one of the most favorite IDEs available these days for Java.
People might prefer others (Netbeans, InteliJ Idea,...), but for me it's the IDE of choice for some years already. The point of this post is not to do any comparison with others however.
The core technology used in Eclipse is OSGI, that makes it easily extensible. There are plenty of plugins out there, some are well known, however there might be some you've never heard of, but might find them useful, once you see them in action.
I've decided, it's a time for the first mini series in my blog posts.
Let's start with the plugin I've found already quite some time ago... (thanks to my former colleague)
Commenting the source code in a right way is beneficial to whoever using/reading it.
I've seen/read various opinions on code comments. Some where going to extremes, but I basically agree with the one, that all of the API should have comments. In java world it means JavaDocs for the Classes/methods/fields/... should be present.
Of course, if the class design is nice object oriented and understandable, it's easier for others to understand it as well as for the programmer to write the JavaDocs for it.
But if you try to achieve 100% documented API there might be fields, or methods having names descriptive enough so that functionality/idea behind them is clear just by name. For the cases like these, it might be handy to have automated solution. Moreover if you're not happy with Eclipse auto generated javadocs but would still like to use generation for core comments manually providing only fields/method/... specifics, my recommendation is to give JAutoDoc a try.
Installation
As the first thing, we need to install it to eclipse. In my case, I went for update site:
http://jautodoc.sourceforge.net/update/
Test example
Once installation was complete, I restarted eclipse and created sample java project.
Let's assume, we have the class like this:
public class Person {
private String firstName;
private String middleName;
private String surname;
}
Meaning of all the fields is more-less clear. Let's see what JAutoDoc can do for us and compare it with default eclipse generated comments.
Keyboard shortcuts
But at first as I'm a big fan of keyboard shortcuts let's list the relevant ones. The default ones for generating comments on particular element:
- the Eclipse one: Alt+Shift+J
- the JAutoDoc one: Alt+Ctrl+J
That is nice, because we can choose the one we like depending on the case.
And ... action
Eclipse generated JavaDocs:
/**
* @author
*
*/
public class Person {
/**
*
*/
private String firstName;
/**
*
*/
private String middleName;
/**
*
*/
private String surname;
JAutoDoc generated JavaDocs:
// TODO: Auto-generated Javadoc
/**
* The Class Person.
*/
public class Person {
/** The first name. */
private String firstName;
/** The middle name. */
private String middleName;
/** The surname. */
private String surname;
}
Well, I'd say, that it can speed up things, and for the case the comments look nice without a need for later editing.
To make our life even simpler, JAutoDocs enables us to generate comments on all the sellected elements, so if you don't want to go over each and every field and generate is separatelly just select all in editor and push the keyboard shortcut.
Getters/setters case
Let's check what getters/setters case comments look like.
In Eclipse:
- right clicking and going for Source -> Generate getters and setters
- afterwards, selecing all the fields and checking Generate method comments leaves us with the contents
/**
* @author
*
*/
public class Person {
/**
*
*/
private String firstName;
/**
*
*/
private String middleName;
/**
*
*/
private String surname;
/**
* @return the firstName
*/
public String getFirstName() {
return firstName;
}
/**
* @param firstName the firstName to set
*/
public void setFirstName(String firstName) {
this.firstName = firstName;
}
/**
* @return the middleName
*/
public String getMiddleName() {
return middleName;
}
/**
* @param middleName the middleName to set
*/
public void setMiddleName(String middleName) {
this.middleName = middleName;
}
/**
* @return the surname
*/
public String getSurname() {
return surname;
}
/**
* @param surname the surname to set
*/
public void setSurname(String surname) {
this.surname = surname;
}
}
Now let's see what the comments would look like when generated JAutoDoc way:
// TODO: Auto-generated Javadoc
/**
* The Class Person.
*/
public class Person {
/** The first name. */
private String firstName;
/** The middle name. */
private String middleName;
/** The surname. */
private String surname;
/**
* Gets the first name.
*
* @return the first name
*/
public String getFirstName() {
return firstName;
}
/**
* Sets the first name.
*
* @param firstName the new first name
*/
public void setFirstName(String firstName) {
this.firstName = firstName;
}
/**
* Gets the middle name.
*
* @return the middle name
*/
public String getMiddleName() {
return middleName;
}
/**
* Sets the middle name.
*
* @param middleName the new middle name
*/
public void setMiddleName(String middleName) {
this.middleName = middleName;
}
/**
* Gets the surname.
*
* @return the surname
*/
public String getSurname() {
return surname;
}
/**
* Sets the surname.
*
* @param surname the new surname
*/
public void setSurname(String surname) {
this.surname = surname;
}
}
OK, that is much nicer, I'd say.
Up to now, we just scratched the surface with examples. But as you can see, I'm the guy lazy enough to have stuff auto-generated. So you can't expect me to think of some more complicated example, I guess.
Anyway, if you're interested in more real world scenarios, possibly your project, there is no better thing as giving it a try and making up your mind.
To be honest I was really surprised once I've seen it in real world apps used.
More info
If interested, the full list of features can be found on the official web site:
http://jautodoc.sourceforge.net/index.html
To have an idea, following are the plugin options available:
I'm looking forward for the next post in the series. Feel free to suggest the plugins you find useful in your daily work (otherwise I'll stick with my preferred list only).
