THE CURIOUS DEVELOPER

Code style is like politics, everybody has their own opinions and personal preferences. However, when working in a team on the same code base it is necessary that you and your teammates agree on a shared style.

I am not going to get into any arguments on how the code should be styled, it is a suicide mission. Instead, I am going to give a couple of tips on how you can make sure that everybody working on your project writes code that is consequent and follows rules that you together have decided on.

Why do we need to have a shared Code Style?

Working on a project means that you will have to spend many hours per day looking at the code. The code should be easy to read, look good and be consistent throughout the whole project. It’s quite annoying to read code in one file and then switch to another and the structure is completely different. That means that you are going to have to waste time adjusting to a new code style depending on which file you open. A project should have a, and only one code style.

Another important factor is that if different people have different code formatting then you are going to start getting a lot of unnecessary merge conflicts which is something that is never fun to deal with, also if you are using a tool for looking at what code has changed in a commit then it’s not fun and a complete waste of time for some file or lines to be marked as changed when it was just the formatting that slightly changed.

Agreeing on a Code Style

It is important to remember that you are not the only one working in the code base and that means that you and your teammates are going to have to agree on something that you all can live with.

Most of the popular modern IDE’s, for example, Eclipse and IntelliJ, have some sort of functionality where you can instruct the IDE to format the code for you. These settings are usually highly configurable and I recommend that you sit down together with the team and agree on the configuration of the formatting.

In this article, I am going to use the popular Google Java Style Guide that is used in many open source projects. However, you are perfectly welcome to make your own style if you prefer that.

Importing settings to your IDE

I have only used IntelliJ and Eclipse, so that’s what I will provide you instructions for. But if your IDE supports formatting then you should easily be able to find it on google.

Start with cloning the project Google Java Style Guide to your computer.

IntelliJ IDEA

Open up the preferences and navigate to Editor -> Code Style -> Java and press on the cogwheel and select Import Scheme -> IntelliJ IDEA code style XML and import the file intellij-java-google-style.xml from the project that you just cloned.

Eclise

Open up the preferences and navigate to Java -> Code Style -> Formatter and press on Import and select the file eclipse-java-google-style.xml.

Enforcing the Code Style

Now that you have agreed on a code style and everyone has it configured in their IDE, it is time to start enforcing it. It is easy to sometimes forget to format the code or optimizing the imports and therefore, it may be a good idea to verify it when building the project which is something everyone already should do before committing their changes to verify that it compiles and that they didn’t break any unit tests.

Let me introduce to you Checkstyle. Checkstyle is an extremely useful tool that helps you and your team to write Java code that lives up to a decided coding standard. Checkstyle spares you the boring manual task of verifying that the code adheres to your standard by automating it. Checkstyle can, for example, be set up in Maven or Gradle to be triggered on builds to warn the developer if some code isn’t meeting the standard. It can also be configured to make the build fail if some errors exist.

Checkstyle for Maven

It is extremely easy to get started with Checkstyle in Maven, simply add the following plugin to your plugins in your build tag.

    org.apache.maven.plugins
    maven-checkstyle-plugin
    2.17
    
      
        com.puppycrawl.tools
        checkstyle
        8.5
      
    
    
      
        validate
        validate
        
          google_checks.xml
          UTF-8
          true
          true
        
        
          check
        
      
    

The plugin comes with two default provided configurations; google_checks.xml and sun_checks.xml. The google checks is perfect for us with the google open source formatter.

After adding this and triggering a mvn clean install I get the following in the logs.

[INFO] Starting audit...
[WARN] /Users/viktorplane/thecuriousdev/thecuriousdev-demo-couchbase/src/main/java/org/thecuriousdev/demo/skeleton/configuration/CouchbaseConnector.java:30:3: Missing a Javadoc comment. [JavadocMethod]
[WARN] /Users/viktorplane/thecuriousdev/thecuriousdev-demo-couchbase/src/main/java/org/thecuriousdev/demo/skeleton/util/QueryResultChecker.java:16:3: Missing a Javadoc comment. [JavadocMethod]
[WARN] /Users/viktorplane/thecuriousdev/thecuriousdev-demo-couchbase/src/main/java/org/thecuriousdev/demo/skeleton/util/Serializer.java:21:3: Missing a Javadoc comment. [JavadocMethod]
[WARN] /Users/viktorplane/thecuriousdev/thecuriousdev-demo-couchbase/src/main/java/org/thecuriousdev/demo/skeleton/util/Serializer.java:27:3: Missing a Javadoc comment. [JavadocMethod]
[WARN] /Users/viktorplane/thecuriousdev/thecuriousdev-demo-couchbase/src/main/java/org/thecuriousdev/demo/skeleton/util/Serializer.java:36:3: Missing a Javadoc comment. [JavadocMethod]
[WARN] /Users/viktorplane/thecuriousdev/thecuriousdev-demo-couchbase/src/main/java/org/thecuriousdev/demo/skeleton/util/Serializer.java:54:3: Missing a Javadoc comment. [JavadocMethod]
[WARN] /Users/viktorplane/thecuriousdev/thecuriousdev-demo-couchbase/src/main/java/org/thecuriousdev/demo/skeleton/controller/PersonController.java:30:3: Missing a Javadoc comment. [JavadocMethod]
[WARN] /Users/viktorplane/thecuriousdev/thecuriousdev-demo-couchbase/src/main/java/org/thecuriousdev/demo/skeleton/db/PersonRepository.java:42:3: Missing a Javadoc comment. [JavadocMethod]
[WARN] /Users/viktorplane/thecuriousdev/thecuriousdev-demo-couchbase/src/main/java/org/thecuriousdev/demo/skeleton/db/PersonRepository.java:54:3: Missing a Javadoc comment. [JavadocMethod]
[WARN] /Users/viktorplane/thecuriousdev/thecuriousdev-demo-couchbase/src/main/java/org/thecuriousdev/demo/skeleton/db/PersonRepository.java:64:3: Missing a Javadoc comment. [JavadocMethod]
[WARN] /Users/viktorplane/thecuriousdev/thecuriousdev-demo-couchbase/src/main/java/org/thecuriousdev/demo/skeleton/db/PersonRepository.java:80:3: Missing a Javadoc comment. [JavadocMethod]
[WARN] /Users/viktorplane/thecuriousdev/thecuriousdev-demo-couchbase/src/main/java/org/thecuriousdev/demo/skeleton/db/PersonRepository.java:102:3: Missing a Javadoc comment. [JavadocMethod]
Audit done.

It looks like I’ve been slacking with the Javadoc, but at least all other requirements are met because I use the google java style formatting in my IDE. The missing Javadoc comes out as just a warning and won’t trigger a build failure, more serious stuff such as indenting and the length of lines would trigger an error.

Final words

We have looked at why we need to have a decided shared code style in a project and how we can maintain and enforce it in our project. It might seem like being too strict, but personally, I believe it is completely necessary in order for everyone to be more productive on a shared project.

Also, keep in mind that code styling is extremely configurable in a modern IDE. If you and your team are not happy with how something is styled, bring it up and decide on something else and do the change in the configuration. Everyone has different personal preferences when it comes to code style, and that is perfectly fine. The only thing that matters is that everyone on the project can agree on something that everyone uses.