Skip to main content

Internal Code Contracts

Your team must define and maintain internal code contracts for the core classes in your system.

An internal code contract documents how your system is structured and what each class or method guarantees to other developers working on the project.

Internal contracts reduce ambiguity inside your team. They define behavioral guarantees between modules, make refactoring safer, improve onboarding, and support reliable testing.

What You Must Produce​

Each core class must include:

  • A clear class-level purpose statement
  • Documentation for all public methods and fields
  • Parameter descriptions and return values
  • Declared exceptions and when they are thrown
  • Preconditions and postconditions where applicable
  • Example usage where helpful

If the implementation changes, the internal contract must change.

Contract Synchronization​

Internal documentation must remain synchronized with the implementation at all times.

  • If a method signature changes, the documentation must change.
  • If an exception condition changes, the documentation must change.
  • If behavior changes, the contract must change.

Documentation drift is considered a contract violation.

Quality Standards​

  • Documentation must describe behavior, not restate method names.
  • Preconditions and postconditions must reflect real constraints.
  • Exceptions must be documented with specific triggering conditions.
  • Method signatures in documentation must match the implementation.
  • Public APIs must not be undocumented.

Missing or inaccurate documentation is considered a defect.

Scope of Documentation​

You are not required to document private helper methods unless they affect public behavior. Focus on documenting the public surface area and core architectural components.

Detailed Guidance​

Use the pages below for templates, examples, and exception/error-handling policies:

Last updated by Ian Applebaum