Applying Java Code Conventions Using Walkmod

Raquel Pau, @raquelpau, Albert Coroleu, @acoroleu

Walkmod is an open source Java tool to apply code conventions. It scans the code and instead of just reporting the invalid source files, it corrects the code automatically.

Web Site: http://walkmod.com/
Version Tested: Walkmod 1.0.5
System requirements: Java 1.6 or higher
License & Pricing: Open Source (Lesser GNU Public License 3)
Support: Google Group https://groups.google.com/d/forum/walkmod

Motivation

It is well known that there are different ways to create software and developers continuously make decisions about how to create and evolve code. Developers do not just need to take into account the involved business rules, but also efficiency, scalability, and maintenance requirements.

In order to achieve a software with a robust architecture and reduce maintenance costs, developers usually discuss about which set of code conventions must be followed by every project contributor. Clearly, when everybody write code with the same style, the code is faster to understand and thus easier to maintain. In fact, important open source companies like Google, Redhat or Apache have specific documentation about their own code conventions.

Currently, there are several QA tools, such as PMD or SonarQube for Java projects to report which source files do not follow a set of code rules. For example, we could apply rules like: "all fields must be private". However, developers need to correct all rule violations manually although the code is straightforward to correct. So, what if there are thousands of files to change or it happens frequently? Correcting code becomes a boring task.

Walkmod pursues to remove these kind of boring and repetitive tasks from the developer’s life by applying code transformations. Therefore, Walkmod makes your code more DRY (Don’t Repeat Yourself) compliant because code conventions are specified in just one place and all of them are applied automatically.

Installation

Installing Walkmod is very easy. You just need to download the binary distribution from http://walkmod.com, unzip the file and add the bin folder into your PATH environment variable.

Now, open your favorite prompt and type walkmod. Then, the console should show something like that:

Maven Integration

You can run Walkmod as a Maven plugin (see http://github.com/rpau/maven-walkmod-plugin) of your build life cycle without performing any installation. You just need to declare the following plugin into your pom.xml

Execution Modes

Walkmod has two main execution modes:

• The apply mode to upgrade your code to satisfy your code conventions.
• The check mode which reports which files need to be changed without upgrading them.

The Walkmod´s output for both modes contains the list of modified, created or deleted files and a summary of the execution process.

Code conventions are achieved by means of code transformations and Walkmod is completely extensible to allow developers to create their own code transformations or use existing ones by means of plugins.

Let’s play!

Let’s remove the unused imports of your Java project using Walkmod. These are the required steps:

Add an empty file called walkmod.xml in the root directory of your project. This file is the core of a project's configuration in Walkmod. It is a single configuration file that contains the majority of information required applying the code conventions of a project in just the way you want. Using the standard maven project structure, it should be as follows:

Copy the following text and paste it to your walkmod.xml.

Replace ${source directory} value with the parent directory of your code or packages (e.g. src/). If you do not want to overwrite existing source files, replace the ${target directory} with another output directory. The default path is src/main/java. If you use the same directory, you can remove the reader and writer tags.

Open a prompt, go to your project directory and type "walkmod apply". It should print out those files that include unused imports.

Are there other available conventions?

The previous example uses just one Walkmod plugin to remove unused imports, but there are other available plugins with different purposes at http://walkmod.com/plugins.html. Check them and select your code conventions!

Alternatively, if your conventions cannot be assured by the current plugins, don’t be afraid - you can extend walkmod to create your custom code conventions. Walkmod supports three possible extension mechanisms:

1. Plugins

Plugins are a set of Java classes to perform complex code transformations using the Visitor pattern. All plugins must be deployed into a Maven repository to share them. This is useful when different projects share a set of common conventions. The following picture shows a skeleton to create a custom code convention for fields and methods.

2. Templates (such as JSPs, velocity …)

Templates are an extension mechanism especially useful to generate code (e.g. to assure a default implementation of the "equals" method in all classes) in a human readable way. If you have experience with code generation tools, you have suffered that these are not usually designed to allow further code modifications once the code has been generated. Otherwise, if you apply manual changes in the generated code, you assume the risk that the tool may overwrite them if it is executed again. To solve this gap, Walkmod provides a powerful merge engine that is completely configurable. So, the user can configure, for instance, whether to replace or not the existing fields or methods for a given class. In short, feel free to change the code generated by Walkmod! It will not overwrite your changes if you do not want.

The following example shows how to build a simple facade pattern with "create" methods for each entity type ("UserAccount", "Group", "Company", …) using Walkmod. For each of them, the template engine produces always the same Java class "AppServices" with just one method called "createXXX", where "XXX" is the name of an entity type. After executing a transformation, if it is mergeable, Walkmod will merge the produced output with the existent content.

The default supported template engine is Groovy.

3. Scripts

Scripts are useful to perform code transformations without deploying them to the Maven repository. The default scripting language is Groovy. The following picture shows a script example whose aim is to assure all fields are private.

Further steps

Walkmod will always keep growing by means of the community through their plugins and the improvements. However, Walkmod team pretends to add more integrations for the most popular development tools (e.g. Jetbrains, Eclipse, Codenvy, Forge, SonarQube, Gerrit).

Moreover, Walkmod team is currently working on "naming conventions" to simplify refactoring tasks and ensure correctness after renames. In fact, a first version of a refactoring plugin (https://github.com/rpau/walkmod-refactor-plugin) is available to automatize migrations or library upgrades.

---

More Java and Programming Knowledge

Java Tutorials Videos and Tutorials

Software Development Videos and Tutorials

---

Click here to view the complete list of tools reviews

This article was originally published in the Fall 2014 issue of Methods & Tools