Why Developing Coding Standards for Your Team Matters
Programmers spend a lot of time reading code. Estimates of the percentage of daily tasks vary, but all results show that the time allocated to reading code is several times larger than the amount of time spent writing code. Conceptually, this makes sense. With the sheer amount of time spent reviewing code, it makes sense to follow coding guidelines.
Developers write code once and likely read it many times, such as in code reviews, debugging sessions, pair programming, or going over it to understand basic concepts. I spend even on my projects, such as Material Design in XAML more time reading code that I authored to understand and debug it than writing new code. It is unsurprising that many other developers strongly advocate for making code readable.
Why Coding Guidelines are Necessary
A set of coding guidelines (sometimes called coding standards or coding conventions) are a way to ensure that an entire team is building a cohesive code base. The goal is to improve the readability, and consequently, the quality of the code. For C#, IntelliTect has our own company coding standards, heavily influenced by our CEO Mark Michaelis’ book, Essential C#, and the Microsoft coding conventions.
Guidelines typically fall into one of two categories: functional and stylistic.
These standards guide you into the proper use of the language or framework APIs. They often have objective reasons to write code in a particular way to avoid bugs and performance issues. One such example of a rule designed to avoid memory issues:
DO implement IDisposable on types that own disposable fields (or properties) and dispose of those instances
These types of conventions are more challenging to agree upon unanimously. As with any written language, each programmer has a particular way they prefer to style their code. Unfortunately, having divergent styles in a single codebase can make it challenging to read. Additionally, variances can cause the quality to suffer and introduce numerous bugs. Below is an example of style guidelines:
DO use PascalCasing for all class names
Steering Your Coding Conventions
Some of the style rules can be contentious. Many, including the one above, are nearly universally accepted because they match the defaults provided by the tooling. This is important to note because the default for these coding guidelines can be controlled within your codebase using an .editorconfig file. Most popular code editors support the EditorConfig specification, making it the easiest portable way to help steer your coding standards.
If you are looking for a good starting reference, the IntelliTect Coding Guidelines repo provides one. Add this file to the root of your repository.
No matter which coding conventions your team decides to implement, having a straightforward convention with tooling support significantly improves your code base’s readability. It can help lower the cognitive load on everyone who needs to read the code, so that making changes is more accurate and quicker. Also, having an established set of guidelines helps us streamline our client projects. As a result, strong communication between our team allows us to communicate well with clients. More so, it allows us to work together as multiple developers on one project.
"At IntelliTect, while we may not do everything the same way, having solid guidelines for our code increases teams’ agility and keeps us focused on delivering value to our customers," Grant Erickson, IntelliTect CTO, said.
Do your coding conventions match IntelliTect’s guidelines? Let me know in the comments which guidelines you would change.