pocketpy/docs/coding-style-guide.md

---

icon: book order: -5

label: Script Style

Script style

These conventions keep pocketpy examples readable and make scripts easier to share with Python users. Runtime restrictions belong in the compatibility guide; style preferences do not change language behavior.

Layout and names

• Use four spaces for indentation and avoid tabs.
• Use CapitalizedWords for classes, lower_case_with_underscores for functions and variables, and UPPER_CASE for constants.
• Give public parameters descriptive names. Short names such as i or x are appropriate when their meaning is clear locally.
• Avoid shadowing built-ins such as list, type, and map.
• Prefix internal helpers with a single underscore. Reserve special __name__ forms for the runtime protocols they implement.

Functions and comments

Use type annotations where they clarify an interface. Keep docstrings short: state what the function does and describe non-obvious constraints or effects. Explain why a step exists instead of narrating obvious operations.

def clamp(value: float, minimum: float = 0.0, maximum: float = 1.0) -> float:
    """Limit a value to the inclusive interval [minimum, maximum]."""
    if minimum > maximum:
        raise ValueError('minimum must not exceed maximum')
    return min(max(value, minimum), maximum)

assert clamp(1.5) == 1.0

Put spaces after commas and around binary operators. For parameters with type annotations, use spaces around the default =; for calls, write clamp(0.5, maximum=0.8).

Choose either string quote style consistently, switching when that avoids escaping. Use triple-quoted docstrings.

Imports and conditions

Group imports by standard modules, optional/native dependencies, then your application modules. Prefer explicit imports over wildcard imports.

Use is None/is not None for the absence of a value. Use direct truth tests for booleans and empty containers:

items = [1, 2, 3]
value = None

if items:
    print(len(items))
if value is None:
    value = 0

Keep resource ownership visible. Explicit cleanup may be necessary because of pocketpy's context manager behavior. For native contribution conventions, consult the repository's contribution guide.