Blog
On Coding Conventions

Coding conventions are rooted in the definition of done.

Definition of Done

Having a definition of done helps to form a common understanding of desirable qualities of a product created by a team.

This definition is not underestimated, as the following quotes account for.

Ten years ago no one had that notion [refers to the "definition of done"]. But I think that through the years the idea that if you just keep putting out feature after feature without considering the quality of it, you could be in trouble.

Laurie Williams. Getting to Comparative Agility

Scrum teams that are unable to master the concept and use of "done" will not succeed.

Ken Schwaber. Done and Undone on Control Chaos

There are definitions of done for tasks, sprints, or releases, but let's stick to user stories. The answer to the question

"What makes a story be considered as done?"

is answered by this definition and the items on this list makes the work required visible to all stakeholders. This list may have numerous items like the following example:

  1. All story tasks are done
  2. All unit tests pass
  3. Coding standards followed
  4. Code is peer reviewed
  5. Code merged in mainline
  6. Acceptance tests passed
  7. Capacity tests passed
  8. Successfully deployed to UAT environment and tests passed
  9. Successfully delivered to customer, passing smoke tests.

The definition of done is defined by the team to meet requirements that are non-functional, also know as a quality attributes: software maintenance for instance.

Coding Conventions

One item one can often find on the 'done list' is that the code must conform to the coding standards defined by the team. Conforming code improves the

readability for all team members. This advances the software maintenance quality. It supports the notion that the team owns the whole code base.

If you look at how most programmers spend their time, you’ll find that writing code is actually a small fraction. 

Martin Fowler. Refactoring

Having tools like Checkstyle, PMD or Findbugs checking the code is not only about automation, but the executable rules also form an instance of a living documentation.

Automation

The definition of done is not static and an agile team works on it to improve the collaborative work and to communicate about it with other stakeholders of the project. The requirements stated in the list are a moving target.

From the point of view of a delivery pipeline the delivery process starts with a commit that may automatically be promoted into production. This requires that all the requirements formulated in the definition of done must also be automatically testable. This automatic tests also help team members to be write code that is conform with the coding standards while working with the editor. They will also be informed about not meeting the requirements by their build server, triggered automatically by the check-in - up to the stage where the manual user acceptance testing tasks can be executed. After the OK by the team the rest of the steps may be taken automatically again.

Automation will give you back something you don’t have enough of: time. 

Mike Clark

Justify Guidelines

And there is a third point - and for me an equally important one: The team should document why a special coding convention is important. This is not only useful for the team to get a common understanding for a given rule, but it also helps new team members to adhere to it. Having a reason makes a rule challengeable. Reasoning is always a good thing.

Conclusion

So the path to my conclusion is this:

  1. Communication is an important part of software development
  2. The definition of done does promote communication
  3. The definition of done also promotes qualities
  4. One such quality is software maintenance that is supported by coding conventions

And the message is

  • Coding conventions are an executable specification for software maintenance requirements
  • All rules of your coding conventions should be checked automatically
  • A justification for the rules should be provided so that the members of the team can understand the reason for enforcing it

Example Configurations

At smartics the configuration for static code analysis is documented by three projects:

  1. config-smartics-checkstyle
  2. config-smartics-pmd
  3. config-smartics-findbugs

We add the justification for our Checkstyle and PMD rules as part of their configuration. To be pragmatic, only controversial rules should be commented. The configurations with their justifications are displayed on the project's website. There may be a better way to format this report than displaying the XML file, but it is enough for a start.

 

The Maven plugin Alias Maven Plugin has been released with version 0.3.0.

The improvement due to Bug 598 is that the console output of extensions is much more readable.

 

 --- ALIAS EXTENSIONS ...aq: taq paq iaq saq sdaq laq raq rpraq rpeaq rraq rcaq -- and-quit: Launches
 the command and closes the shell on successful termination.        On error the
 shell is turned red and beeps for attention.

reads now

--- ALIAS EXTENSIONS
 ...aq (... and quit!): taq paq iaq saq sdaq laq raq rpraq rpeaq rraq rcaq

The user is presented the extension (aq in this case), a short mnemonic (... and quit!) and the list of aliases that have been created by this extension (taq = "test and quit!", paq = "package and quit!", ...).

The Maven plugin bugzilla-maven-plugin has been released with version 0.5.3.

This is a bugfix release due to Bug 597 that prevents Maven plugin and archtetype projects from syncing with a Nexus server for the latest version number.