Skip to content

Code Standards

This document outlines the coding standards and practices used in the ethereum/execution-spec-tests repository.

Code and CI Requirements

Code pushed to ethereum/execution-spec-tests must fulfill the following checks in CI:

Type Tox Command Explanation
Lint & code formatting uvx --with=tox-uv tox -e lint Python lint, format and module import check via ruff
Typecheck uvx --with=tox-uv tox -e typecheck Objects that provide typehints pass type-checking via mypy.
Framework unit tests uvx --with=tox-uv tox -e pytest All framework unit tests must execute correctly.
EL Client test cases uvx --with=tox-uv tox -e tests-deployed All client test cases for deployed forks can be generated.
zkEVM EL Test cases uvx --with=tox-uv tox -e tests-deployed-zkevm All client test cases specific to zkEVMs for deployed forks can be generated.
HTML doc build uvx --with=tox-uv tox -e mkdocs Documentation generated without warnings.
Spellcheck uvx --with=tox-uv tox -e spellcheck Code and documentation spell-check using codespell.
Markdown lint uvx --with=tox-uv tox -e markdownlint Markdown lint (requires additional dependency).
Changelog validation uvx --with=tox-uv tox -e changelog Validates changelog entries format and structure in docs/CHANGELOG.md.

Avoid CI surprises - Use pre-commit hooks!

We strongly encourage all contributors to install and use pre-commit hooks! This will run fast checks (lint, typecheck, spellcheck) automatically before each commit, helping you catch issues early and avoid frustrating CI failures after pushing your changes.

Install with one simple command: 

uvx pre-commit install

This saves you time by catching formatting issues, type errors, and spelling mistakes before they reach CI.

Running checks easily

Add an alias:

alias tox="uvx --with=tox-uv tox"

Run all checks in parallel:

uvx --with=tox-uv tox run-parallel

Run sequentially:

uvx --with=tox-uv tox

Run specific, faster checks:

uvx --with=tox-uv tox -e lint,typecheck

Lint & code formatting: Using ruff and VS Code to help autoformat and fix module imports

On the command-line, solve fixable issues with:

uv run ruff check --fix

Use VS Code, see VS Code Setup, to autoformat code, automatically organize Python module imports and highlight typechecking and spelling issues.

Typechecking

Adding the correct typehints can sometimes be tricky and there are exceptions that require manually disabling typechecking on a per-line basis. Please reach out to the maintainers if you need help, either directly or in a PR.

Python Coding Preferences

  • Line Length: 100 characters maximum.
  • Formatting: Enforced by ruff (similar to black).
  • Documentation: All public functions and classes should have docstrings
    • Docstrings should have a good one-line summary which uses the imperative ("Return" not "Returns").
    • Add a blank line after the summary for multi-line docstrings.
    • Single-line docstrings should have triple quotes on the same line.
  • Imports: Use explicit imports (no from module import *).
  • Relative Imports: Use relative imports within the same package
  • Error Handling: Use explicit exception types and meaningful error messages.
  • Type Hints: All functions should include type annotations.
  • Variable Naming:
    • Use snake_case for variables, functions, and modules.
    • Use PascalCase for classes.
    • Use UPPER_CASE for constants.
  • File Paths: Strongly prefer pathlib over os.path for file system operations.

Editor Setup

A correctly configured editor will automatically handle most formatting requirements. See VS Code Setup for recommended settings.

Detailed Information

See the Detailed Code Standards page for more information on: