The Case for Strict and Opinionated Style Guides or: The “Because I Said So” Approach
Developers come and go throughout the life of a project, and they all tend to have their own personal coding nuances. With no style guide, no standardization, no rules, no linter, no style cop, etc., the codebase’s style – or lack-there-of – will inevitably become quite messy. Indeed, “messy” is in the eye of the beholder but stick with me for a minute while I make a case for enforcing a strict and opinionated style guide.
I recently began working on a new project, which is composed of an Angular web app and a handful of backend projects using C# and .NET Core. I had just come off two other projects, one C#, and the other Swift. The former had a vague set of style rules which were not captured in any documentation or reference, and the latter used SwiftLint in a nearly useless way. Here’s a quick breakdown of what we did and why, in my opinion, it didn’t work well:
The Swift Project
Problems
- SwiftLint was not used from the get-go.
- SwiftLint gave too many warnings for things that nobody cared about (e.g., file size too long, line length too long, etc.).
- There were too many warnings, so they just became noise to developers.
- Because the warnings were just noise and generally thought of as nitpicky style rules, they obscured warnings for real things that should’ve been addressed immediately.
- Almost everything was just a warning, so almost nothing would cause a build to fail.
- SwiftLint errors would not fail a build in our Continuous Integration pipeline.
Our Solutions
- Made the SwiftLint rules less strict! Sure, all the same style problems were still there, but at least we weren’t nagged by SwiftLint about them.
- Took the Boy Scout approach (“always leave a campground cleaner than you found it”)! While we’re working in there, we’ll just clean up a warning or two at a time.
The C# Project
Problems
- Style was not discussed in the beginning, at all.
- There was no official style guide that anybody could look to.
- As there was no style guide, there was no tool to enforce the style guide.
- The project began across a handful of non-collocated developers, working on many different pieces, using various IDEs and styles.
- Developers came and went.
- The codebase became very messy in a variety of ways.
Our Solutions
- A new lead developer came onto the project, and we quickly realized that there was no style consistency between developers. We agreed upon some general rules of thumb, which were not documented, and then proceeded to take the Boy Scout approach (see above) to set things right.
If you read the solutions above and thought, “those solutions sound awfully bad.” I agree, and that’s why I’ve set out to solve all those problems in my latest project. Fortunately for me, I am in a position to do this. Here’s what I don’t want to happen in this new project:
- Any developer thinking about style. This includes code reviewers. Why, you ask? Well, why does Ian Malcolm only ever wear two colors? Deciding what to wear each morning is a waste of his valuable time, so he liberates himself from this time-waste by only ever wearing two colors (Jurassic Park, Michael Crichton). Liberate yourself with a tool that styles your code for you.
- Warnings to be ignored. Why even show the warning if you’re not going to do something about it? If it’s a problem that needs to be fixed, it should be an error. Otherwise, it’s just noise.
- Any developer to have to take the Boy Scout approach to keep the code base clean. If it never gets dirty, it never has to be cleaned up.
- Any developer to not know where to local the style guides and rulesets.
How do I intend to achieve these goals?
- I have created style guides for each project type (as a reminder, Angular and C# in the projects in question). They are easily accessible to everybody in the project. Each style guide is concise, but, for the most part, nobody needs to read them. TSLint will enforce the style guide of the Angular app, and StyleCop will enforce the style guide of the C# projects.
- Each style guide is enforced at build time.
- Each style guide is enforced in the CI/CD pipelines. A build will not pass with style violations.
- There are no style warnings. For example, any StyleCop rule that would be a warning by default has either been removed (because warnings of this type are useless) or elevated to an error. I describe this ruleset to coworkers as being somewhat fascistic, but stricter.
To be clear, I don’t mean to force anybody whoever works on this project to write code in my way. I mean to force them to write code in a way that is standardized and unified. On this project, it may be my way. On the next, it could be your way. But if we all know the rules, I’m happy either way.
