Book: SE@Google Ch 8: Style Guides and Rules

[jonahtanjz]

Book: Software Engineering at Google
Chapter 8: Style Guides and Rules

Summary:

• Having coding rules within an organisation is crucial and important.

  • Rules encourage "good" behaviours and discourage "bad" behaviours. The "good" and "bad" can be subjective and varies between organisations, depending on what they care about.
  • Some examples of rules are code formatting, name and location of source files (folder structures) and naming and patterns of methods and variables.
  • Rules ensure that there is a common vocabulary of coding between the engineers within the same organisation.

• When creating rules, focus on the goals instead of simply picking which rules should the organisation have.

  • Identifying rules that will be serving the goals will ensure that they are not redundant.
  • Not everything should become a rule as this will make it challenging and time consuming for engineers to remember and maintain the rule set.
  • Rules should be easy to understand for the readers.
  • Rules should be consistent.
  • Rules should ensure that there are no error-prone and surprising constructs as these can be easily misused and introduce bugs.
  • Rules should be practical.

• Style guides are a set of rules to help engineers avoid dangers, enforce best practices and ensure consistency.

• Style guides are not static, they can change with time.

  • If a new language version is released, rules should be updated to allow or exclude new features and idioms.

• Rules and style guides can be enforce through teaching and training or with tooling.

  • It is best for engineers to use automated tools to check for compliance instead of relying on engineer-based verification.
  • Automation also ensures that rules are not dropped or forgotten as time passes.
  • Automation will also minimise the variance in how a rule is interpreted and applied.
  • Tooling makes enforcement scalable.