Credo: Writing a Style Guide

TL;DR Jesus, another style guide? Really? Yep, one for Credo.

Credo, a code linter foccusing on code consistency and teaching best practices, has just seen the release of v0.2.0, passed the 300-star-mark on GitHub and was downloaded over 5,000 times from hex.pm. I thought this was a good reason to open source the document I wrote before implementing it.

Why did I write a “style guide”?

IMHO, the situation is this:

• community style guides are a fantastic way to represent how you could structure your code and there is great value in having this in Open Source
• AND some companies even adapt them into their own style guides

But, as a matter of fact, most companies (or teams, really) have a style they tend to follow to a certain extent, but never write this style down to form a coherent guide of the “do’s and don’ts”.

When you then employ tools to check coding styles you have to configure those rules whenever you deviate from the community guideline. And, since this has to happen for the most trivial of things like the old “tabs or spaces” discussion, you end up with a thousand line long config file.

So I sat down and tried to write my own personal style guide, but I tried hard to differentiate between cases where I have strong opinions (e.g. “don’t use unless with else”) and where it doesn’t really matter what you do, as long as you do it in a consistent manner (as in the “tabs or spaces” debate). I also tried to reflect how my own coding habits changed after reading a lot of open-source Elixir code.

This document, originally on the clean side of a napkin, then became the basis for Credo.

Since every code linter needs a coherent style guide which it runs against and Credo does not follow any of the existing style guides, I decided to polish this document up and publish it on GitHub.

Like always: Feedback is very much welcome! Find me on Twitter or create an issue on GitHub.