Code Style

DL-Learner Code Style

Currently, we use checkstyle and PMD to test our code style. Here is a quick tutorial to use checkstyle on DL-Learner in Eclipse:

  • checkout DL-Learner in Eclipse
  • install the Eclipse checkstyle plugin – see the update below
  • go to “window“ >> “preferences“ >> “checkstyle“ (or “project“ >> “properties“ >> “checkstyle“) and specify doc/checkstyle.xml in your DL-Learner directory as external configuration file for checkstyle (this file contains the rules we consider useful for DL-Learner)
  • in Eclipse package explorer right click, go to checkstyle and let you show checkstyle warnings
  • go to package org.dllearner.parser and disable checkstyle warnings there (the parser is automatically generated, i.e. we cannot change its code style)

If you violate any of the checkstyle rules, this will be shown as Eclipse warning. You can also run checkstype on single packages or classes.
Some of the enabled rules are:

  • missing Javadoc for public/protected methods shown
  • incomplete Javadoc reported
  • checks whether licence header is present
  • parameters separated by comma and space
  • curly brackets on same line

Open issues / Best Practice:

  • @Override: checkstyle claims that Javadoc is missing, but in fact such methods do not need to be documented (the documentation is copied over from the interface or super class); workaround: add an additional /** {@inheritDoc} */ to such methods — Javadoc should never be duplicated
  • Delegate methods: Unfortunately, there seems to be no nice way to document delegate methods. The best thing to do at the moment seems to include a shortened version of the method we delegate to.
  • Convenience methods with incomplete parameters: Often, you have several convenience methods, e.g. method(int) may call method(int,String,int) by just using defaults for the last two parameters. There seems to be no nice way to document this. As best practice, the most complex method (including the actual implementation) should be documented in detail, whereas the other methods should include a copied or shortened version of the Javadoc.

Let us know if there are further issues.

Update: Checkstyle 5.0beta solves the @Override problem (and possibly others specific Java 5 or higher). It is recommended to install it, instead of the previous version. To to this, go to https://sourceforge.net/project/showfiles.php?group_id=80344, download it and extract it in your source folder. (If you have a previous version of checkstyle, make sure you uninstalled it first.)

Differences between Checkstyle 4 and 5: In doc/checkstyle.xml you need to rename JavadocPackage to PackageHtml if you use Checkstyle 4.