arrow_back_ios_new

Synced automatically from infinity-project/rulebook (main) at build time – edit the source repository, not this file.

Code documentation

← Back to index

Documenting code creation

All code contributions must include clear and consistent documentation as the code is created, to ensure:

  • Readability: Humans and AI agents can understand the code easily
  • Maintainability: Future contributors can extend or debug code
  • Automation: AI-based tools can generate summaries or integrate with doc systems

Use block comments or notebook-style markdown cells (for Jupyter notebooks or similar workflows) to describe what the upcoming code block does.

  • Each comment block should summarize purpose, inputs, outputs, and side effects.

Place inline comments sparingly for non-obvious operations.

  • Avoid over-commenting trivial code (e.g., i += 1 # increment i).

Every function or class must have documentation explaining:

  • Purpose of the function/class
  • Arguments and expected types
  • Return value and type
  • Exceptions raised (if any)
  • Example usage (if helpful)
  • Use language-specific comment standards (e.g. Javadoc, Python docstrings)

Each source file/module should have a header comment describing:

  • Purpose of the file
  • Contributor(s) and maintainers
  • Date created / version
  • Dependencies and imports
  • High-level description of contained classes or functions

AI tools may be used (e.g. GitHub Copilot or other programming-language-aware documentation generators) to:

  • Generate initial docstrings or comments
  • Suggest clearer names and block headers
  • Create summary descriptions for notebooks or modules

However:

  • All AI-generated documentation must be reviewed and finalised by a human contributor
  • The use of any AI tool must be credited in the repository

In general, code documentation guidelines recommend:

  • Language-appropriate style: Follow PEP257 (Python docstrings), Javadoc (Java), or equivalents
  • Consistency: Use the same comment symbols, block headers, and spacing across the repository
  • Readable line length: Limit comments to ~80–100 characters per line
  • Notebook-style markdown: Use headings (###) to separate blocks and provide context

Code quality management

All submitted code must follow strict quality requirements.

Code style

Projects must adopt a defined style guide such as:

  • PEP8 (Python)
  • ESLint + Prettier (JavaScript)
  • Rustfmt (Rust)
  • gofmt (Go)

Testing requirements

Every project must include:

  • Unit tests
  • Integration tests (when applicable)
  • Minimum test coverage threshold (recommended ≥ 80%)

Continuous integration

Repositories must include automated CI pipelines that run:

  • Code tests
  • Security scans
  • Linting
  • Dependency checks

← Previous: Code development and testing · Back to index · Next: Software and data management →