Your Style Guide Is Worthless

3 minute read

When many people (with “many” being >= 2) work on a project it is important to lay down rules that all developers ought to follow lest everyone starts doing whatever the heck passes their mind.

The first, and probably most important rule, is to force everyone to write in a single, uniform, style so that code looks like it was written by a single person. Software developers spend most of their time reading each other’s code after all.

This is how “The Style Guide” is born.

The pinnacle of software engineering civilization is an endless stream of words written on a wiki somewhere, by someone who is no longer working at the company. A text nobody reads nor follows because, let’s be honest for a moment here, when I’m solving a problem I don’t know nor care about your whitespace rules. I just want to bang some code on the keyboard to fix the problem at hand and then call it a day. Fixing style problems and cleaning up code usually comes at a later phase, if at all.

Don’t forget the political problem of “why do I have to follow Bob’s advice on this? He’s an asshole, he doesn’t get programming. I’ll get the last word on this one.”, which is a surefire way to waste everybody’s time and money fighting office politics. So, bonus points if conventions come from outside, so that any complaint can be immediately choked to death with a generic “they (the language designers) want that, not my fault”.

The point is, writing a style guide just for your project or company is a waste of time, unless you want to exercise your technical writing chops, in private.

Design automated tools and community-wide style guides instead, so that all code in the world written in a particular programming language looks like it was authored by the same person.

Thankfully, during the last ten-or-so years, I’ve seen many communities doing just that. Python has PEP-8 and PEP-257, go has gofmt, Ruby has a community-led style guide and so on.

Go, however, is the role model to follow here since, for the most part, doesn’t even have a lengthy style guide. It has automated tools to fix mechanical style violations and others to warn about code smells 1. Integrations with most editors are readily available for built-in and 3rd party tools alike for maximum productivity. From day one. All of this is possible because Go includes libraries to parse source code right into the standard library, which makes it really easy to work on the AST and manipulate source code (take that, C++ 2).

If you are designing a new programming language, or working on an emerging one, take care to ship version 1.0 with a complete style guide and tools to parse, manipulate, validate, and fix source code. Every minute we don’t have to spend bike-shedding and following tedious issues that can be automated is a minute we can spend writing awesome code in your programming language. It’s in your best interest to make us, the users, happy and productive.

As for me, I will refrain from using new programming languages that don’t provide many of the facilities that I’ve come to expect from Go, Python, Java, and C/C++ (to a lesser extent) 3.

Footnotes

  1. Some of them are shipped with the compiler and all others can be easily installed with go get.

  2. C++ is famously the most difficult programming language to parse, which explains why, until clang appeared, many IDEs (with the exception of Visual Studio) couldn’t offer decent auto-complete support.

  3. I’m talking to you, Rust.