Code Style¶

This guide covers formatting and visual presentation of code. For guidance on code organization, patterns, and architectural decisions, see Practices.

For comprehensive language-specific development guidance (including formatting), see:

Python Development Guide - Python development guide with formatting standards
Rust Development Guide - Rust development guide with formatting standards
TOML Configuration Practices - TOML configuration guide with formatting standards

This document provides general principles applicable to all languages.

General¶

Lines and Spaces¶

Use spaces between identifiers and other tokens. Modern writing systems use this convention, which emerged around the 7th century of the Common Era, to improve readability. Computer code can generally be written this way too… also to improve readability.
No more than 79 columns for code lines. (Borrowed from the Python PEP 8 guidelines.) Consider the following:
- Will long lines display well on laptop screens? (Might not be hooked up to a larger monitor while flying or in a meeting.)
- Will long lines display well in side-by-side code panes with enlarged font sizes? (Enlarged font sizes are used to reduce eye strain and allow people to code without visual correction.)

Vertical Compactness¶

Loop bodies, condition bodies, and exception handlers, which consist of a single statement and which are sufficiently short, should be placed on the same line as the statement that introduces the body.

❌ Avoid:

if not data:
    return None

for item in items:
    process( item )

try:
    value = risky_operation( )
except ValueError:
    return default_value

✅ Prefer:

if not data: return None

for item in items: process( item )

try: value = risky_operation( )
except ValueError: return default_value

Blank lines should not be used to group statements within a function body. If you need to group statements within a function body, then perhaps the function should be refactored. Similarly, avoid obvious comments. Only include comments which explain subtle nuances or reference external documentation for additional context.

❌ Avoid:

def complex_process(data: __.cabc.Mapping[ str, __.typx.Any ] ) -> dict[ str, __.typx.Any ]:
    # First phase - validation
    if not data: raise ValueError( "No data." )
    validated = validate_data( data )

    # Second phase - processing
    processed = transform_data( validated )
    cleaned = clean_data( processed )

    # Final phase - output
    result = format_output( cleaned )
    return result

✅ Prefer:

def complex_process(
    data: __.cabc.Mapping[ str, __.typx.Any ]
) -> dict[ str, __.typx.Any ]:
    if not data: raise ValueError( "No data." )
    validated = validate_data( data )
    processed = transform_data( validated )
    cleaned = clean_data( processed )
    result = format_output( cleaned )
    return result

Function bodies should not be longer than thirty (30) lines. I.e., one should not have to scroll to read a function.

Language-Specific Development Guides¶

For comprehensive development guidance including formatting standards:

Python Development Guide - Python development guide
Rust Development Guide - Rust development guide
TOML Configuration Practices - TOML configuration guide

Automation¶

Currently, there are no tools which can automatically enforce compliance with the above style guidance. However, if you politely ask an LLM, which is good at instruction following, to make your code conform to the guidance, results will generally be good. If you are familiar with isort and yapf, you can also look at Python: Automatic Formatting for approximate formatter configurations for these tools.
Cases where manual intervention may be needed:
- Multi-line chains of method invocations. (Fluent programming.)
- Function declarations with mixed positional and nominative arguments.
- Nested data structures with mixed single-line and multi-line sections.
When in doubt, optimize for readability while staying within the general principles outlined in this guide.