langston-barrrett.github.io
Meta Style Guide
This guide is targeted at authors of style guides that are scoped beyond an individual project, context, or circumstance.
The recommendations in this guide are split into three levels, based on the author's perception of their relative importance and applicability:
- Strongly Recommended: These recommendations are broadly applicable and have a high value-to-weight ratio.
- Recommended: These recommendations may apply less universally, or be less than essential to a strong style guide.
- Nice to Have: These recommendations aren't essential to writing a decent style guide; they're more like the marks of a really high-quality style guide.
Furthermore, the recommendations within each of the above categories are sorted in rough order of descending importance.
Do you have ideas for this guide? Contact me!
Strongly Recommended
Acknowledgment of Limitations
A style guide should acknowledge that:
- its prescriptions are not absolute,
- the guide is non-exhaustive,
- the authors are fallible, and
- each recommendation has a set of trade-offs (pros and cons) that need to be weighed in each context in which a recommendation is considered.
Examples
My Python style guide states:
This is my personal style guide for writing Python code. As with all style guides, this guide is incomplete, fallible, and its recommendations aren't appropriate for every circumstance.
The Google C++ style guide states:
If you understand what goals each rule is serving, it should be clearer to everyone when a rule may be waived (some can be)
and:
As always, common sense and good taste should prevail.
Justification
Such an acknowledgment establishes credibility: If the style guide is perceived to be pedantic, or the work of authors who are incapable of recognizing nuance and acknowledging subjectivity, its content and message will be proportionately less compelling.
Justification
Each item in a style guide should include a discussion of why the particular recommendation is made. Where appropriate, such justifications should:
- explicitly name the goals or concerns that the recommendation addresses,
- discuss the trade-offs (pros and cons) of the recommendation (especially relative to the explicitly-named goals), and
- refer to alternative solutions or styles and discuss their trade-offs.
Examples
In the Google C++ style guide, the list of goals appears before all the recommendations and provides context for evaluating them.
Justification
Given the inherent limited scope and applicability of style guides, a thorough discussion of trade-offs for each recommendation aids users in considering them "à la carte".
Justifications also educate readers. Recommendations in style guides are sometimes the product of hard-won experience, and sharing the experience alongside the recommendation may help others internalize it.
List of Recommendations
A style guide should consist of a list of recommendations.
Justification
Formatting style guides as a list of recommendations allows readers to consider them "à la carte" for their specific circumstance, which is crucial given that style guides are inherently limited scope and applicability.
It also makes it easy to refer to a specific recommendation when describing it to others.
Recommendations Should Pull Their Weight
As described in the Google C++ style guide:
The benefit of a style rule must be large enough to justify asking all of our engineers to remember it.
Examples
This style guide doesn't explicitly call out that style guides should be written in a language that is widely understood among the target audience, because this is assumed to be in the "background of obviousness" - the shared set of assumptions and understandings between the author and the majority of the audience.
Also from the Google C++ style guide:
for example,
gotocontravenes many of the following principles, but is already vanishingly rare, so the Style Guide doesn't discuss it.
Justification
Narrowing the scope helps keep the guide relatively concise and focused on higher-leverage recommendations. This increases the overall value of the reading and applying the style guide, relative to other approaches to increasing project quality.
Recommended
Naming an Audience
Style guides should explicitly name an audience.
Examples
This is a JavaScript style guide aimed at first-time programmers who are learning JavaScript and are looking for guidance on writing readable, maintainable code.
This is an in-house Haskell style guide for Company X. It's aimed at intermediate Haskell programmers working at Company X who want to write code that is in-line with the pre-existing style that's widely used across our codebases.
Justification
Naming an audience helps readers quickly evaluate whether or not the majority of the recommendations will apply to their circumstance.
Moreover, it establishes a context in which to evaluate the addition or omission of recommendations (see Recommendations Should Pull Their Weight.
Naming a Scope
In addition to naming an audience and prioritizing the recommendations, style guides may also name a scope that delimits which recommendations are considered for inclusion.
Examples
The Google Java Style Guide says:
this document focuses primarily on the hard-and-fast rules that we follow universally, and avoids giving advice that isn't clearly enforceable (whether by human or tool).
Justification
This shares most of the benefits of Naming an Audience.
Prioritization
Recommandations should have an associated level or degree of importance or applicability.
Examples
This guide is split into three sections: "Strongly Recommended", "Recommended", and "Nice to Have".
The Google TypeScript style guide uses the terminology of RFC 2119 (e.g., "SHOULD", "MAY", "MUST", etc.).
Justification
All style guide recommendations are circumstantial, and so such prioritization is equally circumstantial. However, if the reader finds many of the recommendations in a given guide to be useful, they are likely to also agree with the degree of importance that the authors assign to their recommendations. The reader can then focus on applying the recommendations that provide them with highest value first or most stringently, increasing the overall utility of the guide.
Examples
Each recommendation should be accompanied by at least one example. Both positive and negative examples are helpful.
Examples
This example is an example of including an example.
Justification
Including examples is a concise way to confirm (or develop) a reader's understanding of what situations are being referred to by the recommendation.
Nice to Have
Identifiers and Permalinks
Each recommendation should have some specific way of being referred to.
Examples
- Each recommendation could have an immutable identifier that doesn't change between versions
- Each recommendation could have a number in a list that may change between versions, but old versions could be made permanently available
Justification
Pros: This makes it easy to refer to specific recommendations with little effort, and with the confidence that the reasoning behind your decisions will be faithfully preserved online.
Cons: May entail more work for the style guide author.
Automation
Where the enforcement of a given recommendation can be automated, a style guide should include a reference or description of how to do so.
Examples
The Google Python Style Guide recommends use of Pylint with a specific configuration file.
Style guides might also just list a particular rule identifier for a given tool, or have an inline snippet of a semgrep rule. (However, inline linter rules or scripts for automation should be very short or hidden by default for the sake of brevity).
Justification
Automation reduces the cognitive and time burdens of enforcement: a team can decide to adopt a recommendation and then never need to discuss it or bring it up in code reviews again, because they use tooling that enforces it.
Moreover, the authors of style guides are often the sort of people who know more about tooling for enforcing stylistic/best practice recommendations, and so are in a good position to write or recommend such tooling.