Code Health: Styles and Conventions

As a software developer we spend much, if not all, of our day in front of our computer screens reading code. Notice I said “reading” code and not “writing” code. This certainly varies from day to day, but in general, I spend much more time reading through our codebase than I do actually making changes.

For me, this stems from a saying my dad used to share with me “Measure twice, and cut once”. To understand how a potential change is going to fit into the existing code base, I have to understand what the existing code does and how it works.

If it’s easier to understand my code, it’s easier to find errors. It’s also then easier, and faster, to fix those errors. Less time fixing bugs leaves more time for adding features to my project and therefore value to the end user. The point I’m trying to make is that having clean, consistent, easy-to-read code can have a significant positive impact on a project.

There’s plenty that can be talked about in regards to writing clean, easy-to-maintain code (design patterns, SOLID design principles, MVVM vs MVP, etc) but lately I’ve been thinking about something much smaller.

Having recently joined a new team and inheriting a code base that has had half-a-dozen different contributors come and go over its lifespan, I’ve been spending a lot of time reading code that looks exactly like it was written by half-a-dozen different devs all with a unique style. One class may use Hungarian Notation while the next doesn’t. One screen might be implemented using an MVP architecture while another uses MVVM and others are simply monolithic monstrosities. In some places ternary statements might be heavily favored while others break things into separate if/else statements.

All of these differences make if difficult to jump into different parts of the code and immediately comprehend what is happening. They can also lead to additional errors. For example, if one piece of code is written/documented to handle null while another was written assuming client code would handle null it’s very likely that at some point something will break. Having to read through these disparate styles also adds time to code review and increases the likelihood that errors will be missed during the review.

To improve the health of our codebase, and therefore the quality of our project I’be began documenting/defining/incorporating our common coding conventions and styling preferences. This is a multi-tier approach involving the following:

Defining a project code style shared between developers Defining common IDE inspections so all team members are being warned about the same issues Creating a wiki page describing general conventions, common styling practices, and pointing out interesting/useful aspects of the code such as useful custom annotations used to add common documentation across the project Going through this process has really forced me to think about how we write code, and by doing so I’ve been able to start developing our core set of conventions and to define our standard style. When these styles and conventions are then applied to existing code (IDE formatting tools make this part so wonderfully easy) it immediately becomes easier to work with.

Individual files and pieces of code start to read and feel like cohesive parts of a whole rather than individual classes written by different people. Not only does this make the project more maintainable, but it increases the sense of “team” by making it harder to determine who wrote a piece of code. Yes, there are always tools like Git blame that will tell you where the code came from, but I believe that as you navigate a code base, you shouldn’t be able to tell who wrote what without using one of these tools. If everything looks the same, and reads the same, then everyone can, and should, take responsibility for maintaining it.

Having code that is easy to read/maintain for all contributors, new and old, is a small but important step that your team can take to promote a healthy codebase and ultimately provide a better product for your users.

Leave a Reply