Why a Style Guide?
For the same reasons that style guides exist anywhere humans need to exchange information via symbols - to enable consistency, engender familiarity and, thus, improve readability.
Before we tackle why readability is so important for code, let us examine how consistency and familiarity play their part in enabling it.
Why care about Consistency?
Consistency and familiarity go hand-in-hand to improve readability. Let us take writing in English as our example.
You might be able to muddle through a sentence wiz unuzal speling, but it increases the cognitive load. Spaces between words, types and usages of punctuation, paragraph breaks - these are all elements of style that we expect to be used consistently within the content in question to allow us to quickly parse it. Only once we can successfully parse the content can we begin the process of understanding and synthesis - so every bit of inconsistency stands between us and the actual meaning of the content.
Consistency between different codebases enables familiarity, which is much like shared conventions between one book and the next - you know to look for a table of contents, and how to use it to find the page you want, with no need to learn a new content indexing method on a per-book basis.
That's not to say that no work of modern English ever establishes its own idiosyncratic style, and in some cases this is necessary or valuable; but consistency must then be maintained with its own style to avoid constantly confusing and alienating the audience. And even then, seldom are certain shared elements of style abandoned, and only at great peril - you would not have made it this far if I had decided to abjure spaces between my words.
So it is with code. Consistency within the codebase allows us to spend a minimum amount of time and effort on parsing the content, and instead quickly begin to comprehend the meaning of statements. Consistency between codebases enables familiarity, allowing us to move from one codebase to another without requiring a taxing learning curve just to understand how the content is laid out - we can instead begin the process not just of reading, but of understanding the code that much faster.
Why care about Readability?
Assuming you accept the arguments above about how consistency and familiarity contribute to readability, why should we care about readability?
Someone naive to the realities of software development might think of code as something that is simply written once and run, never to be looked at again.
An amateur might recognize that they will need to dig back into the codebase every now and then to fix bugs or make changes.
A professional recognizes that not only they, but likely any number of others may need to read their code, understand it, and make modifications to it. Even if they start the project alone, it may someday pass into someone else's hands for a variety of reasons - the original developer is no longer available, the project size or scope has increased to include multiple developers, the codebase has been forked to support multiple different projects, etc.
Given that fact, improving readability is doing a service to yourself and others. You will be glad for the consistent style upon needing to return to the project weeks, months or years later - you will not need to relearn how to read your code before you can come to grips with it again; and your fellow developers will be grateful for the shallow learning curve as they join you in maintaining the codebase.
How does this Style Guide help?
This Style Guide explains how we arrive at consistency, familiarity and readability: We explain some coding principles, provide linting files for use with style checking/enforcement tooling, and discuss setup of auto-formatters.
We offer linting files for all the languages we typically employ in development, for those languages that support them; we also discuss what to do if the language you're working with doesn't offer support for these sorts of tools yet.
My Project is Different
There's two situations where your codebase may not cleave to the conventions and rules set out in this style guide:
- A legacy project: A project that has been running for some time may not have started under the same regime. For some time, A+L maintained a purely manually-enforced style guide, and projects often paid it less attention than they might have. It is expected that active projects will slowly but surely take on use of the linting files and tools discussed within this style guide. If yours doesn't yet, bring it up with your Project Manager or Project Supervisor.
- A client codebase: Clients often bring existing codebases to us for us to continue, improve or refactor the work done by another developer. These developers will (hopefully) have their own styles; often times they have no consistent style enforced, and each source file, or even each function, is a brand new adventure. Over time, we expect to bring these codebases in line with a consistent style, but depending on client budget and project timeline, we may not be there yet.
Language Independence and the Language Ecosystem
Another area where there are some significant differences between projects is when considering different languages.
Rather than attempt a one-size-fits-none approach to all languages, this Style Guide and the accompanying linting files recognize the essential differences between languages and the conventions that have grown up around them in the larger ecosystem for that language.
All of our linting files are based on community standards for the language in question, with only those modifications that have proven useful and needful to our developers included. Moving between an open-source project in your language of choice that adheres to the general wisdom and style of the community and an A+L project should prove low-friction and comfortably familiar.
Code Snippets
This document contains occasional code snippets to illustrate the points being made; several of the languages used at A+L are used for these examples. Many of them are not complete pieces of code, and we count on the reader to supply the missing context that would permit these snippets to make sense.
In this document, code examples are
const formatted = "like this."