Solidity Style Guide

Solidity Style Guide — Claude Code Skill

Use this skill whenever you are reviewing or writing Solidity, Foundry tests, or related configuration. It codifies the rules in Aboudjem/solidity-style-guide targeting Solidity 0.8.34.

When to invoke

Trigger automatically on:

• .sol files in the workspace
• foundry.toml, remappings.txt, .solhint.json present
• User says: review my contract, clean up this Solidity, apply the style guide, is this gas-optimal?, make this audit-ready

Output contract

1. Produce a checklist of violations grouped by category (layout → naming → formatting → NatSpec → best practices → tests → gas → security).
2. Quote the offending snippet with file path and line number.
3. Propose a minimal diff that makes it compliant. Preserve behavior; style changes only unless asked.
4. Cite the rule inline, e.g., [§Best Practices > Using Custom Errors Over Require].
5. Stop before applying unless the user asked for an auto-fix.

Hard rules (block the review on violation)

Files & layout

• SPDX license identifier on every .sol file
• One contract / interface / library per file; filename matches the core type
• Top-level order: pragmas → imports → events → errors → interfaces → libraries → contracts
• Inside a contract: type declarations → state vars → events → errors → modifiers → functions
• Function order: constructor → receive → fallback → external → public → internal → private
• Within each visibility group, put view then pure last

Imports

• Named imports only: import {X} from "./X.sol";
• Sort by path length within groups; blank line between external and internal
• No wildcard imports

Pragma

• Applications: pin to a single version — pragma solidity 0.8.34;
• Libraries / mixins: open range — pragma solidity ^0.8.20;
• Never ^0.8.0 ^0.9.0 or other multi-constraint forms

Types

• Always explicit: uint256, int256, bytes1 — never uint, int, byte
• bool booleans, not uint flags
• Prefer bytes over string when non-human-readable

Naming

Formatting

• 4-space indent, spaces (no tabs)
• Max line length 120 chars
• Strings in double quotes
• One space around binary operators; no space inside parens / brackets
• mapping(K => V) — no space after mapping
• uint[] — no space before []
• Braces on same line as declaration; else on the same line as the closing brace
• Long signature: each arg on its own line, closing ) and { on their own lines

Best practices

• Prefer custom errors. Use require(cond, CustomError(arg1, arg2)) when on Solidity ≥ 0.8.26 (via-ir) or ≥ 0.8.27 (legacy). Otherwise if (!cond) revert CustomError(...);.
• If a require string message is unavoidable, keep it under 32 bytes.
• calldata for read-only array / struct params on external functions.
• Cache .length before the loop header.
• Prefer named returns for functions with ≥ 2 return values.
• Prefer named arguments in calls, events, errors with ≥ 3 parameters.
• Named parameters in mappings: mapping(address user => mapping(address asset => uint256 amount)).
• Interact with external contracts through typed interfaces; if using call, use abi.encodeWithSelector.
• For upgradeable contracts, use ERC-7201 namespaced storage with @custom:storage-location erc7201:<namespace>.
• Events in past tense: OwnerUpdated, FundsDeposited.
• Avoid inline assembly unless there is no high-level alternative; when used, document every opcode.
• Prefer composition over inheritance.

NatSpec

• @title, @author, @notice, @dev, @param, @return on every public / external function
• Internal / library functions used by other devs: also NatSpec

Foundry testing conventions

• File naming: MyContract.sol ↔ MyContract.t.sol; split large: MyContract.owner.t.sol, MyContract.deposits.t.sol
• Test names: test_Description, testFuzz_Description, test_RevertWhen_Condition, test_RevertIf_Condition, testFork_Description, testForkFuzz_RevertIf_Condition
• Invariants: invariant_Property (e.g., invariant_TotalSupplyEqualsSumOfBalances)
• No assertions inside setUp; use a dedicated test_SetUpState
• Verbose assertion messages: assertEq(x, y, "Invariant violated: …")

Gas patterns

• Mark values set once as immutable; mark compile-time values as constant
• Prefer uint256 over smaller ints unless packing is intentional
• Hoist array length out of loops; use unchecked { ++i; } where safe (Solidity ≥ 0.8.22 already optimizes simple ++i increments, but unchecked still helps for custom counters)
• Use transient storage (tstore / tload, EIP-1153) for per-transaction flags like reentrancy locks when the EVM target supports it (Cancun+). Solidity 0.8.34 default EVM is Prague.

Security

• Checks → Effects → Interactions
• Reentrancy guard (mutex) around any external call that precedes state writes
• call{value: x}("") for Ether transfers; always check the returned bool
• No tx.origin for authorization
• Pull over push payment patterns where feasible

Invocation recipes

/solidity-style-guide:review

Scan the repo, produce a categorised violations report, do not edit.

/solidity-style-guide:review --fix

Apply the minimal formatting and naming diffs (no logic changes) and print a summary. Behavior-changing rewrites remain advisory.

/solidity-style-guide:apply-config

Copy the .solhint.json, .prettierrc, .editorconfig, and .prettierignore from this repo into the current project (do not overwrite if present without asking).

References

• README — full rule catalog with ✅ / ❌ examples
• Solidity Style Guide (official)
• Foundry Best Practices
• ERC-7201 Namespaced Storage Layout
• EIP-1153 Transient Storage Opcodes
• Coinbase Solidity Style Guide
• RareSkills Solidity Style Guide