Notes on enforcing code formatting (#195)

Author: walteck

patterns/automate-everything.md

@@ -35,9 +35,10 @@ Regularly review *every* manual process that the team performs. Automate it, but
 * Automated [tests](../practices/testing.md).
 * Automated [security](../practices/security.md) verification.
 * Automated [governance](governance-side-effect.md).
+* Hooks to [enforce code formatting](enforce-code-formatting.md).
 
 ## Examples — how to automate
 
 Some automation is highly managed and is purely declarative. e.g. VM or container auto scaling in cloud platforms can typically be achieved without the need to write any code: the platform implements scaling based on specified rules.
 
-Programmatic automation by contrast typically involves writing code and involves the use of **orchestrators** such as CI tools (e.g. Jenkins, Circle CI), AWS Step Functions or Lambda triggers and **runners** which do the actual work (e.g. bash or Python scripts). The orchestration and runner logic should all be represented in code with everything that entails (see [everything as code](everything-as-code.md)).
+Programmatic automation by contrast typically involves writing code and involves the use of **orchestrators** such as CI tools (e.g. Jenkins, Circle CI), AWS Step Functions or Lambda triggers and **runners** which do the actual work (e.g. bash or Python scripts). The orchestration and runner logic should all be represented in code with everything that entails (see [everything as code](everything-as-code.md)).

patterns/enforce-code-formatting.md

@@ -0,0 +1,29 @@
+# Enforce code formatting
+
+## Context
+
+* These notes are part of a broader set of [principles](../principles.md)
+
+## The pattern
+
+Being consistent with your code formatting improves readability, and maintainability of your code base. Where consistency is enforced prior to commits being pushed this ensures that commits are cleaner and easier to manage.
+
+## Benefits
+
+* Reduces the need for changes to include formatting updates across non impacted code.
+* Improves clarity of code.
+* Enables teams to agree on formatting that is important to them up-front.
+
+## Details
+
+* Teams should agree on linting tools for their code.
+* Teams should agree the rules around formatting for their code.
+* These tools should be used to ensure that commits are not merged where code does not meet the agreed ruleset.
+* Teams should implement pre-commit hooks to check developers commits and fail to push changes that do not adhere to the agreed format.
+* Tools should provide useful output on failures - ideally auto formatting the code for developers to accept.
+* Developers can then apply formatting changes as part of their development process.
+* Teams should also employ a specific step in their CI/CD pipeline to verify that code is formatted to the agreed standards.
+
+## Examples
+
+* Python code formatting could use Black to enforce formatting on a repo.

patterns/everything-as-code.md

@@ -47,7 +47,7 @@ While effective testing is the best way to detect bugs or non-functional problem
   * Does it handle edge cases?
 #### Of high quality
   * Is the code clear and simple?
-  * Is the code layout and structure consistent with agreed style and other code?
+  * Is the code layout and structure consistent with agreed style and other code? (please see [enforce code formatting](enforce-code-formatting.md))
   * Would it easily allow future modification to meet slightly different needs, e.g. ten times the required data size or throughput?
   * Have the non-functional requirements been considered (performance, scalability, robustness, etc)?
   * Are common security issues guarded against (e.g. [OWASP Top 10](https://owasp.org/www-project-top-ten/))? Including: