Category Archives: Java

Enhanced find usages support in NetBeans >= 7.1

In my opinion, Netbeans is one of the most intuitive Java IDE today, especially when it comes to maven development. There was just one missing feature I was always upset about. The IDE was not indexing classes and their dependencies in the local maven repository. So it was not possible to find referenced classes contained in maven projects that weren’t opened  in the IDE. This is quiet annoying if you need to gain an overview of the code, or you have to track down one specific misbehavior especially if you work with hundreds of maven projects.

So, together with Netbeans contributors (mainly Jesse Glick), we’ve worked out a solution for the problem.

The class dependencies were found by bytecode parsing and then indexed with Lucene for very fast search results. All classes from the JDK are excluded to reduce the overhead.

Find Usages in action

In the following example, I selected the class “org.apache.maven.artifact.ArtifactUtils” and searched with “Find Usages” for all referring classes. The class is used as an import in one of the classes in the only loaded maven project  “Maven Release Plugin”.

This gave me the following output:

Under the node “Maven Repository: local” are all hits listed found in the local maven repository. This enables the developer to quickly scan all interesting artifacts without the need to open any maven project in Netbeans.

For now, only the class name is highlighted and linked to the corresponding class located in the maven artifact. I plan to implemented the same behavior as seen as in the search results for already opened projects, in this case “Maven Release Plugin” which features enhanced line highlighting and more precisely jumps to the source code.

Conclusion

It took my some time to get used to a small part of the massive code base of Netbeans and it’s API’s but it felt good to give something back to the community.

Last but not least, I was able to improve my knowledge in programming across the board which was a lot of fun!  😎

 

Sinn & Unsinn von {@inheritDoc}

Ich wurde schon des öfteren nach code-reviews darauf angesprochen, wieso ich bei meinen überschriebenen Methoden nicht immer {@inheritDoc}  im javadoc deklariere. Ich halte dieses Vorgehen bei 90% der Fälle als überflüssig und unübersichtlich. Um dies zu erläutern habe ich ein paar javadoc Tests durchgeführt…

Es wurden die Klassen ParentClass und ChildClass erstellt, wobei ChildClass von ParentClass erbt und die Methode “methodToOverride()” überschreibt.

Gezeigt werden code-Schnipsel aus ChildClass und dem entsprechend generierten Javadoc.

Methode überschrieben ohne Javadoc

 

Wird kein Javadoc angegeben, so wird die Beschreibung der überschriebenen Methode automatisch referenziert. Fügt man allerdings einen Kommentar hinzu, wird das Javadoc wie folgt generiert:

Methode überschrieben mit Javadoc

 

Nun ist das Javadoc der überschriebenen Methode aus der Klasse ParentClass nicht mehr direkt ersichtlich, sondern wird durch den passenderen Kommentar ersetzt.

Methode überschrieben ohne Javadoc mit {@inheritDoc}

 

Wird auf einen Kommentar verzichtet und wird wie leider des öfteren nur {@inheritDoc} angegeben, so hat man ein ähnliches, wenn nicht schlechteres Resultat, wie wenn man kein javadoc schreibt! Der Kommentar wird 1:1 kopiert und die Information welche Methode das ursprüngliche javadoc beinhaltet ist verloren. Damit wird der Quellcode unnötig aufgeblasen und Informationen verschenkt.

Methode überschrieben mit Javadoc und {@inheritDoc}

 

Im Javadoc ist ersichtlich, dass der Kommentar aus der Beispiel-Methode (Javadoc of overriden method) am Ende angefügt wurde.

Der eigentliche Sinn von {@inheritDoc} liegt darin den Kommentar der überschriebenen Methode aus der parent Klasse wiederzuverwenden und mit dem der child Klasse zu ergänzen. Das Tag ist somit ein simpler Platzhalter, welcher nur Sinn macht, wenn die Methode wie im gezeigten Beispiel teilweise überschrieben wird. Dies ist allerdings “bad practice” und sollte wenn möglich vermieden werden, da dies den code sehr verstrickt und kompliziert macht. Desweiteren ist durch das Setzen des leeren Tags später im Javadoc nicht mehr klar ersichtlich, zu welcher Methode der Kommentar ursprünglich verfasst wurde. (siehe 1. Beispiel: “Description copied from class: ParentClass”)

Methode überschrieben mit Javadoc und @Override

 

 

Ab Java 1.5 sollte @Override verwendet werden um überschriebene Methoden klar zu kennzeichnen.

Methode überschrieben ohne Javadoc und @Override

 

Die annotation hat aber keinen Einfluss auf die Generierung des Javadocs wie man in diesem Beispiel sehen kann. Wurde kein Kommentar verfasst, so wird dies signalisiert und derjenige der parent Methode angezeigt wie in Beispiel 1.

Dieses Vorgehen ist zur Kennzeichnungs überschriebener Methoden im Vergleich zu @inheritDoc viel kompakter und man verliert keine Informationen darüber, zu welcher Methode der Kommentar ursprünglich verfasst wurde. Deshalb sollte der Einsatz von @inheritDoc nur beschränkt in Betracht gezogen werden. Desweiteren werden die @Override annotations bei einigen IDE’s deutlich hervorgehoben um eine noch bessere Übersicht zu gewähren und um zusätzliche Funktionen bereitzustellen.

Weiterführende Links

Automatic Copying of Method Comments:

http://download.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html