Catalog
concept#Software Engineering#Governance#Quality Assurance

Code Formatting

Conventions and rules for consistently formatting source code to improve readability and maintainability.

Code formatting defines consistent whitespace, indentation, line breaks and naming conventions to make source code readable and maintainable.
Established
Low

Classification

  • Low
  • Technical
  • Design
  • Intermediate

Technical context

GitHub/GitLab CI pipelinesEditor plugins (VSCode, JetBrains)Pre-commit hook tools

Principles & goals

Prioritise readability over personal preferences.Automate formatting where possible.Separate style changes from functional changes in reviews.
Build
Team, Domain

Use cases & scenarios

Compromises

  • Automatic reformatting can clutter commit history.
  • Inconsistent application leads to merge conflicts.
  • Poor communication leads to team resistance.
  • Enforce automatic formatting on commit or before merge.
  • Make the style guide documented and easily discoverable.
  • Keep style changes in separate commits from functional changes.

I/O & resources

  • Existing source code
  • Style guide or coding conventions
  • Formatter tool and EditorConfig
  • Consistently formatted code
  • Automated CI checks
  • Documented style guide

Description

Code formatting defines consistent whitespace, indentation, line breaks and naming conventions to make source code readable and maintainable. It standardises style across teams, reduces friction in code reviews and tooling, and enables automated enforcement. Its scope covers conventions, editor settings and CI-based formatters.

✔

  • Improved readability and faster code reviews.
  • Fewer style discussions in pull requests.
  • Easier automation and tool integration.

✖

  • Cannot cover all stylistic preferences.
  • Initial effort to configure and enforce.
  • Overly strict rules may frustrate developers.

  • Number of style commits

    Measure how many commits contain primarily formatting changes.

  • PR discussion duration

    Average time spent on style discussions in pull requests.

  • CI format failure rate

    Share of builds failing due to formatting issues.

Python project using PEP8 and Black

Using Black for automatic formatting aligned with PEP8 conventions.

Web frontend with Prettier

Prettier as the standard formatter for JavaScript/TypeScript/HTML in CI and editors.

C++ project with clang-format

Automatic reformatting in the build pipeline, consistent codebase across teams.

1

Analyse existing codebase and identify deviations.

2

Select and configure a suitable formatter and EditorConfig.

3

Integrate formatting into pre-commit hooks and CI pipeline.

4

Communicate rules, train team, and apply incrementally to codebase.

⚠️ Technical debt & bottlenecks

  • Large backlog tasks to reformat legacy modules.
  • Inconsistent history due to late massive reformatting.
  • Technical debt from unsupported formatter versions.
Legacy codeDiverse developer editorsUnclear style rules
  • Enforcing project-specific style that is incompatible with tools.
  • Completely reformatting entire repositories in a single commit without review.
  • Ignoring functional changes because format checks fail.
  • Formatter configurations that produce unexpected changes.
  • Non-versioned editor settings lead to inconsistencies.
  • Enforcing too early without stakeholder alignment.
Basic knowledge of the target programming languageUnderstanding of CI/CD configurationsExperience with formatter tools
Code readabilityAutomatability in CI/CDConsistency across modules and teams
  • • Existing codebase with many style deviations
  • • Limited CI resources for extra checks
  • • Language- or platform-specific formatter differences