Skip to content

Clean Code Engineering Standard

Version: 1.0.0

Status: official

Author: Enterprise AI Standards

Description

Official engineering standard defining mandatory clean code principles, conventions and practices for all enterprise software projects.

Objective

Produce software that is readable, maintainable, testable and easy to evolve by following consistent engineering practices.

Philosophy

Code is read far more often than it is written. Every decision must prioritize clarity, simplicity and maintainability over clever or complex solutions.

Principles

  • Readability over cleverness.
  • Simplicity over complexity.
  • Maintainability over shortcuts.
  • Explicit over implicit.
  • Composition over inheritance.
  • Immutability by default.
  • Single Responsibility Principle.
  • Continuous refactoring.
  • Self-documenting code.
  • Small incremental changes.

Project Structure

Language Features

Virtual Threads

Structured Concurrency

Records

Sealed Classes

Pattern Matching

Collections

  • Return empty collections.
  • Immutable collections preferred.
  • Choose appropriate implementation.

Streams

Optional

Exceptions

  • Never swallow exceptions.
  • Fail fast.
  • Custom exceptions extend RuntimeException.
  • Exceptions are exceptional.

Logging

Performance

Security

Testing

  • Test behavior.
  • Tests independent.
  • Deterministic tests.
  • Fast execution.

Observability

Documentation

  • README mandatory.
  • Public APIs documented.
  • Architecture documented.

Best Practices

  • Constructor Injection.
  • Immutable Objects.
  • Java Records.
  • Small Methods.
  • Small Classes.
  • Value Objects.
  • Domain Driven Design.
  • Descriptive Naming.
  • Early Return.
  • Continuous Refactoring.

Anti Patterns

  • God Class.
  • God Method.
  • Long Method.
  • Long Parameter List.
  • Primitive Obsession.
  • Feature Envy.
  • Data Clumps.
  • Boolean Parameters.
  • Deep Nesting.
  • Magic Numbers.
  • Magic Strings.
  • Static Mutable State.
  • Circular Dependencies.
  • Duplicate Code.
  • Copy Paste Programming.
  • Premature Optimization.

Review Checklist

  • [ ] Single Responsibility.
  • [ ] Meaningful Names.
  • [ ] Small Methods.
  • [ ] Small Classes.
  • [ ] Constructor Injection.
  • [ ] Immutable Objects.
  • [ ] Tests Updated.
  • [ ] Documentation Updated.
  • [ ] No Duplicate Code.
  • [ ] Sonar Clean.

Examples

References

  • Clean Code (Robert C. Martin)
  • Clean Architecture (Robert C. Martin)
  • Effective Java (Joshua Bloch)
  • Domain Driven Design (Eric Evans)
  • Google Java Style Guide
  • SonarSource Rules
  • Java Language Specification