Crane Code Style Guide

Crane Code Style Guide

Crane follows strict code conventions for consistency and maintainability. This skill covers section headers, imports, naming, and critical compilation rules.

Section Headers

Use 78-character wide comment blocks for major sections:

/​* -------------------------------------------------------------------------- */
/​*                             Section Name                                   */
/​* -------------------------------------------------------------------------- */

Shorter form for subsections:

/​* ------ Feature Name ------ */

Import Organization

Group imports by source, with import aliases:

// External libraries
import {IERC20} from "@openzeppelin/​contracts/​token/​ERC20/​IERC20.sol";
import {SafeERC20} from "@solady/​utils/​SafeERC20.sol";

// Crane interfaces
import {IFacet} from "@crane/​contracts/​interfaces/​IFacet.sol";
import {IOperable} from "@crane/​contracts/​access/​operable/​interfaces/​IOperable.sol";

// Crane contracts
import {OperableRepo} from "@crane/​contracts/​access/​operable/​OperableRepo.sol";
import {OperableTarget} from "@crane/​contracts/​access/​operable/​OperableTarget.sol";

// Test utilities (in test files)
import {Test} from "forge-std/​Test.sol";
import {Vm, VM_ADDRESS} from "forge-std/​Vm.sol";

Import Aliases

Defined in foundry.toml and remappings.txt:

Function Organization

Order functions by visibility:

1. Constructor
2. Receive
3. Fallback
4. External
5. Public
6. Internal
7. Private

Naming Conventions

Parameter Trailing Underscore

All function parameters end with underscore to avoid shadowing:

function transfer(address to_, uint256 amount_) external {
    // to_ and amount_ don't shadow state variables
}

Storage Slot Naming

Use hierarchical dot-notation for storage slot names:

bytes32 internal constant STORAGE_SLOT = keccak256(abi.encode("crane.access.operable"));

Critical: No viaIR Compilation

NEVER enable via_ir or viaIR in foundry.toml.

IR compilation is forbidden because:

• Dramatically slower compilation (10-100x slower)
• Excessive memory usage
• Breaks parallel agent workflows
• Not necessary when code is properly structured

Resolving Stack Too Deep Errors

When encountering "stack too deep" errors, refactor using structs:

// WRONG - too many local variables
function badFunction(
    address tokenA,
    address tokenB,
    uint256 amountA,
    uint256 amountB,
    address recipient,
    uint256 deadline
) external {
    uint256 reserveA = pair.reserveA();
    uint256 reserveB = pair.reserveB();
    uint256 totalSupply = pair.totalSupply();
    // ... stack too deep!
}

// CORRECT - group into structs
struct DepositParams {
    address tokenA;
    address tokenB;
    uint256 amountA;
    uint256 amountB;
    address recipient;
    uint256 deadline;
}

struct PoolState {
    uint256 reserveA;
    uint256 reserveB;
    uint256 totalSupply;
}

function goodFunction(DepositParams memory params) external {
    PoolState memory state = PoolState({
        reserveA: pair.reserveA(),
        reserveB: pair.reserveB(),
        totalSupply: pair.totalSupply()
    });
    // Struct members don't consume stack slots
}

Stack Too Deep Solutions

1. Group parameters into structs: Bundle related function parameters
2. Group intermediate state: Use State or Context structs
3. Use memory for computation: Struct fields don't consume stack
4. Extract helper functions: Split complex functions
5. Use block scoping: Limit variable lifetimes with { ... }

Configuration

Standard Crane configuration:

• Solidity: 0.8.30
• Optimizer runs: 1 (for contract size limits)
• EVM version: Prague
• via_ir: false (ALWAYS)

Additional Resources

Reference Files

• references/​complete-style-guide.md - Full style guide with more examples

Key Files

• /​contracts/​StyleGuide.sol - Reference template
• /​foundry.toml - Build configuration
• /​remappings.txt - Import aliases