Style Guides and Rules

INTRODUCTION

To ensure the time and scale resiliency of a codebase, style guides and rules are followed in any organization. This also ensures that the focus shifts on what to say in code from how to say it.

It doesn't matter what we choose as the style elements but more importantly the fact that we have chosen.

Rules
Rules are more like laws and cannot be violated. They are enforceable and can be disregarded only on a need basis after discussion with the group of persons responsible to ensure style consistency in the organization a.k.a style arbiters.
Style arbiters ensure that style decisions are made with consensus and driven by objectives rather than merely personal preferences. Each decision made should be documented in a reason document to ensure style rules and guides are updated as and when needed in the future.
Guides
Guides on the other hand are a collection of recommendations and best practices.

TIPS

• As such, each language should have an independent style document, but if possible as many elements as possible should be kept the same.
• Optimize for the code reader rather than the code writer.
• If just a few engineers are getting something wrong, it doesn't deserve to be part of the style document.
• Expect engineers to leave explicit evidence of the intended behavior of code.
• Be consistent, it enables expert chunking (a cognitive process that helps in grouping pieces of information in chunks rather than individually).
• Consistency starts locally. file-level > team-level > larger-project-level etc.
• Consistency is vital but adaptation is the key.
• Avoid error-prone and surprising constructs.
• Concede to practicalities when needed.
• Change style document based on the solution to existing code and not some hypothetical use case.
• Enforcement should be automated, using tools like clang-tidy for C++.
• Some code formatters:
  • C++: clang-format
  • Python: yapf
  • Buildsystems: buildifier

REFERENCES:

1. Chapter 8: Style Guides and Rules, Book: Software Engineering at Google, Publisher: OReilly.
2. Header Image: https://www.pexels.com/photo/orange-and-white-seashell-on-white-surface-33234/