Developing on Staxmanade

Habit of a Solid Developer - Part 2 - Automatically Enforce Project Conventions


This article is Part 2 of 11 in a series about Habit of a Solid Developer.

Every project generates it's own constraints. These may come from an Architect's idea of "best practice" or it may come from the domain the software is written in. It may even be derived because of the programming language you're using. For example, in JavaScript we have linters that encourage rules like triple equals === vs double equals ==.

Whatever the convention or rule is, one of the best steps you can take is to find a way to automatically enforce the convention once it can be established.

The class of conventions can encompass a wide array of rules; anything from the formatting of the code, naming conventions, to obscure ways of doing X with component Y that if not done in that way will cause problems.

Finding a way to automatically check and enforce conventions will help to not only keep the project on track if a newer developer is onboard and isn't aware of the convention to even catching the most senior developer when they forget the convention all together (It's happened to me - forget).

An example of a project convention

In the past, I worked on a mutual fund and stock trading engine. This entire system depended heavily on time in various places like billing, trading, etc. Deep down in the core of the application we built in an abstraction over the core Date implementation. This abstraction allowed us to do things like roll the date back for testing or debugging purposes or simulate billing over time rages.

However, if someone ever used a new Date() in the code, this would break the convention by not using our abstraction and not allow us to roll time properly. This could lead to serious or hard to find bugs.

Detecting the miss-use of Date in this application was a great place for automated enforcement.

The above can be caught by running code reviews. However, we baked this convention into the system and automated the enforcement of it so that the issue could be caught much earlier in the development lifecycle. With a well-placed a unit/integration test that searched through the code base for uses of new Date() and raised an error message explaining why, we were able to be sure the projects convention was held and avoid potential bugs in the future.

Fail with a solid path forward

In the automated convention enforcement described above, the convention would not just fail a test with a generic do not use new Date()... message.

This is a good place to document or share a story about why new Date() was not allowed. We failed the test with a long error message that described both why not to use new Date() and we included a sample snippet of what to use in its place.

You want to include the why as well as the what here to make adoption of the conventions easier going forward for those new to the team or project.

Allow special exclusions

Most conventions are generalizations that may not ALWAYS be necessary or ideal. There often exceptions to the rule in software development, so allowing the test code to be extended to enable exclusions to this rule is a good thing.

In the example above we had a place in the unit test that allowed us to say "In component M method Y we allowed the use of a single case of new Date()". The first exercise of the exclusion was built in to the original abstraction over time. But there were a couple other places we allowed it as I recall.

Some automation approaches

Depending on the convention, the approach to automation can vary. Sometimes it's as easy as adding a simple unit test. Other times it requires you jump out to a command line utility that searches the entire codebase.

Whatever the convention, try to come up with a simple approach that can automatically be run through a continuous integration environment and can freely be there to watch over you and your team's conventions.

Tools to help enforce conventions

I've started to compile a small list of tools that you may consider to help enforce conventions on your team. Please feel free to suggest others by submitting a pull-request.

Happy Automating!