“all of this we need to drive through a set of universally accepted guiding principles” — Dan North
Whilst there had been attempts at Redgate to establish coding guidelines in the past, they hadn’t really ‘stuck’; attempts to define them from scratch got bogged down in the shear scope of the challenge.
To jump start the process, and to give people something to rail against, Jeff found a set off the internet (what can possibly go wrong) and these gave us a set to work with.
Aviva Solutions C# Coding Guidelines: csharpcodingguidelines.com
Alongside the website, there is also a link to download the detailed guidelines, as well as a ‘Cheat Sheet’. But click through to make sure you get the latest version.
An example of a Coding Guideline might be:
Maintainability Guidelines: Methods should not exceed 7 statements (AV1500)
This is a good guideline as the human mind can only really remember about 7 things at a time —the reader can quickly see the intent of the method without brain strain. Personally I aim for 3 or 4 lines, but 7 gives you some leeway.
Also remember these are guidelines, sometimes it is necessary to have a larger method, but honestly, I remember only 2 or 3 occasions when I needed a significantly larger method, and that was a very specific control algorithm that I couldn’t break down. You should have a good reason to break them.
With very short notice, and using Redgate’s 10% time, where people are given half a day a week to learn and develop and stay up to date with technologies, we ran a workshop to identify the points of agreement and contention amongst everyone in the development staff.
Layout is a distraction. Too much time has been spent in holy wars over whether brackets should be on a new line, or at the end of one. I’ve known developers get into Bracket Wars(TM) over this, with one committing in one style, then another undoing it in the next commit. And don’t get developers started on whitespace. Ever.
Meh. Let the automatic formatter (and its default settings) work that one out.
No, let’s spend our time on the meaty ones that matter.
Such as Naming.
Naming is hard. Naming is usually done when you know least about the problem, and in some cases you can be stuck with it forever - renaming a version control repository can be all but impossible. I once* called something TheBeanWithNoName temporarily, whilst I worked out what it did.
We asked all the attendees their views, and these ranged from some fresh from 12 week code camp courses, to fresh grads, all the way to senior developers, Redgate’s Tech Leads and Jeff as Head of Product Engineering. Everyone had a voice.
First of all we split into groups and some of the groups were asked to consider the anti-problem. By flipping the problem on its head you encourage more creative (divergent) thinking; constraints suddenly aren’t constraints, and idea’s aren’t ‘boxed-in’. So here, we asked some of the groups to consider ‘What would be the worst rules for naming we could adopt’, so examples included:
- names should only be a single character, or
- names must be 128 characters long
Out of the Anti-problem answers you can often extract a good rule (by flipping it again), and it’s amazing how often the insight wouldn’t have got to directly.
Reviewing the standard set of coding guidelines and collating the thoughts of each group, we found they had no problem with roughly 80% of the guidelines, but about 20% were more contentious (does that sound like the Pareto Principle to you?).
Then we gave the groups time to look through the rest of the guideline areas — including Design, Maintainability and Framework. And again 80% were contentious, which allowed us to focus on the remaining 20%.
Whilst some time for discussion was allowed, any that were disagreed with we asked the disagreer to submit an ‘Issue’ on github where we had put up the version controlled set of guidelines.
We also asked for any that people felt were missing; so I myself submitted the guideline “Prefer Immutability”, as I have found that to be a huge advantage on projects I’ve worked on.
Since the workshop there has been some great discussion about the merits (or otherwise) of various guidelines, and a number of further guidelines that we perceive to be missing.
We have actively encouraged contributions from the full spectrum of experiences, including some currently fresh from a Clean Code course, and issues have been turned into updates to the repository.
The Redgate Coding Guideline Repository: codingguidelines.red-gate.com
As the New Year approaches, any last outstanding issues will be settled, by Redgate’s Technical Leads if it comes to it and the new guidelines should be in place for 2019.
Obviously we’ll have a lot of code that won’t immediately be guideline-compliant, but these things must be evolved over time. There needs to be a good reason for it not to conform, and we expect teams to update code when they touch it.
*As you can tell, I was working with Java at the time.