A community-driven registry for Claude, Cursor, Windsurf, Cline & more. Not affiliated with Anthropic.
Are you the author? Sign in to claim
AI-ready Solidity style guide for Solidity 0.8.30 — naming, layout, NatSpec, custom errors, ERC-7201 storage, transient
Consistent. Safe. Gas-aware.
A practical style guide for modern Solidity, tracking 0.8.34, ERC-7201 namespaced storage, EIP-1153 transient storage, and current Foundry conventions.
Solidity gives you enough rope to ship fast or to lose funds. The official style guide covers formatting; this one covers the patterns that prevent audit findings and waste gas.
✅ Yes and a ❌ No example.require, ERC-7201, and Pectra-era defaults.| Target version | Solidity 0.8.34 pinned for apps, ^0.8.20 for libraries |
| Scope | Naming, layout, formatting, NatSpec, best practices, Foundry tests, gas, security |
| Tooling | Solhint · Prettier · EditorConfig · CI |
| Editor context | AGENTS.md · CLAUDE.md · llms.txt · .cursorrules |
| Companions | Official guide · Foundry Book · RareSkills · Coinbase |
Drop the configs into your project, install two dev dependencies, and you're linting and formatting in under a minute.
# 1. Pull the configs
curl -O https://raw.githubusercontent.com/Aboudjem/solidity-style-guide/main/.solhint.json
curl -O https://raw.githubusercontent.com/Aboudjem/solidity-style-guide/main/.prettierrc
curl -O https://raw.githubusercontent.com/Aboudjem/solidity-style-guide/main/.editorconfig
# 2. Install
npm i -D solhint prettier prettier-plugin-solidity
# 3. Lint and format
npx solhint 'src/**/*.sol'
npx prettier --write 'src/**/*.sol'
Claude Code — drop the bundled skill into .claude/skills/, then call it by name.
mkdir -p .claude/skills && cp -r skill .claude/skills/solidity-style-guide
# inside Claude Code:
/solidity-style-guide:review
Cursor, Codex, Aider — they pick up AGENTS.md and .cursorrules automatically once the files sit at the repo root.
Any LLM-backed tool — point it at llms.txt for a token-efficient index of the rules and configs.
This guide is designed to provide coding conventions for writing Solidity code, ensuring consistency and readability. It is an evolving document that will adapt over time as new conventions are established and old ones become obsolete.
[!NOTE] This guide is intended to extend, not replace, the official Solidity style guide, covering additional important aspects not addressed by the existing guidelines .
As Solidity and its ecosystem evolve, so too will this style guide. It will incorporate new best practices, discard outdated ones, and adapt to the changing needs of the community.
[!TIP] 💡 Regular updates ensure that the guide remains relevant and continues to promote the latest best practices in Solidity development .
The primary goal of this guide is consistency, not necessarily correctness or the best way to write Solidity code. Consistency helps improve the readability and maintainability of codebases.
[!IMPORTANT] "A foolish consistency is the hobgoblin of little minds." Consistency with this guide is important, but consistency within a project or module is even more crucial. Use your best judgment and adapt as necessary .
This introductory section sets the stage for a comprehensive style guide, emphasizing the importance of adaptability, consistency, and extending existing best practices in Solidity coding.
Use 4 spaces per indentation level.
[!TIP] 💡 Consistent indentation enhances code readability and structure, making it easier to follow and maintain.
Spaces are the preferred indentation method. Avoid mixing tabs and spaces.
[!WARNING] ⚠️ Mixing tabs and spaces can lead to hard-to-debug errors. Stick to spaces for consistency.
✅ Yes:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.0 <0.9.0;
contract A {
// ...
}
contract B {
// ...
}
contract C {
// ...
}
❌ No:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.0 <0.9.0;
contract A {
// ...
}
contract B {
// ...
}
contract C {
// ...
}
Within a contract, surround function declarations with a single blank line. Blank lines may be omitted between groups of related one-liners (such as stub functions for an abstract contract).
✅ Yes:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.6.0 <0.9.0;
abstract contract A {
function spam() public virtual pure;
function ham() public virtual pure;
}
contract B is A {
function spam() public pure override {
// ...
}
function ham() public pure override {
// ...
}
}
❌ No:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.6.0 <0.9.0;
abstract contract A {
function spam() virtual pure public;
function ham() public virtual pure;
}
contract B is A {
function spam() public pure override {
// ...
}
function ham() public pure override {
// ...
}
}
[!IMPORTANT] Proper spacing helps visually separate different sections of your code, making it easier to read and understand.
Limit lines to a maximum of 120 characters. For long lines, follow these wrapping guidelines:
Function Calls
✅ Yes:
thisFunctionCallIsReallyLong(
longArgument1,
longArgument2,
longArgument3
);
❌ No:
thisFunctionCallIsReallyLong(longArgument1,
longArgument2,
longArgument3
);
thisFunctionCallIsReallyLong(longArgument1,
longArgument2,
longArgument3
);
thisFunctionCallIsReallyLong(
longArgument1, longArgument2,
longArgument3
);
thisFunctionCallIsReallyLong(
longArgument1,
longArgument2,
longArgument3
);
thisFunctionCallIsReallyLong(
longArgument1,
longArgument2,
longArgument3);
Assignment Statements
✅ Yes:
thisIsALongNestedMapping[being][set][toSomeValue] = someFunction(
argument1,
argument2,
argument3,
argument4
);
❌ No:
thisIsALongNestedMapping[being][set][toSomeValue] = someFunction(argument1,
argument2,
argument3,
argument4);
Event Definitions and Event Emitters
✅ Yes:
event LongAndLotsOfArgs(
address sender,
address recipient,
uint256 publicKey,
uint256 amount,
bytes32[] options
);
emit LongAndLotsOfArgs(
sender,
recipient,
publicKey,
amount,
options
);
❌ No:
event LongAndLotsOfArgs(address sender,
address recipient,
uint256 publicKey,
uint256 amount,
bytes32[] options);
emit LongAndLotsOfArgs(sender,
recipient,
publicKey,
amount,
options);
[!CAUTION] 🚨 Long lines can be difficult to read and understand. Breaking them up improves clarity.
Use UTF-8 or ASCII encoding for Solidity files.
[!NOTE] Consistent file encoding ensures compatibility and prevents encoding-related issues across different environments and tools.
[!TIP] 💡 UTF-8 should be preferred over ASCII as it supports a wider range of characters.
Rule: Use the latest stable version of Solidity. At the time of writing that is 0.8.34 (released Feb 18, 2026), a bugfix release patching an IR-pipeline issue around clearing transient storage variables. Recent releases bring material wins: transient storage (tstore / tload) since 0.8.24, MCOPY since 0.8.25, require(cond, CustomError()) since 0.8.26 (via-IR) / 0.8.27 (legacy), custom storage layouts and experimental EOF since 0.8.29, and the Prague EVM default since 0.8.30.
For application contracts, pin the version:
pragma solidity 0.8.34;
For libraries, mixins, and reusable components, use an open floor so downstream consumers aren't forced to upgrade in lockstep:
pragma solidity ^0.8.20;
Older tooling (certain Slither rules, some audit shops) may still recommend a slightly older version. Prefer the latest stable unless there's a concrete blocker.
[!TIP] 💡 Subscribe to the Solidity releases blog and bump your pin alongside each new minor.
Import statements should always be placed at the top of the file.
A. Placing Imports
Organize imports clearly at the top of the file to make dependencies easier to manage and understand.
✅ Yes:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.0 <0.9.0;
import "./Owned.sol";
contract A {
// ...
}
contract B is Owned {
// ...
}
❌ No:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.0 <0.9.0;
contract A {
// ...
}
import "./Owned.sol";
contract B is Owned {
// ...
}
[!NOTE] Organizing imports clearly at the top of the file makes dependencies easier to manage and understand.
B. Use Named Imports
Named imports or Selective Imports help readers understand what is being used and where it is declared.
✅ Yes:
import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
❌ No:
import "@openzeppelin/contracts/access/Ownable.sol";
[!NOTE] Named imports provide clarity on what is being imported, reducing potential confusion and making code review easier.
C. Order Imports by Path Length
Order imports by the length of their paths, from shortest to longest, to maintain a clean and organized structure.
✅ Yes:
import {Math} from "./Math.sol";
import {Ownable} from "../access/Ownable.sol";
import {ERC20} from "../../token/ERC20.sol";
❌ No:
import {Ownable} from "../access/Ownable.sol";
import {ERC20} from "../../token/ERC20.sol";
import {Math} from "./Math.sol";
[!TIP] 💡 Ordering imports by path length improves readability by maintaining a consistent structure, making it easier to locate and manage dependencies.
D. Group Imports by External and Internal
Separate external and internal imports with a blank line and sort each group by path length.
✅ Yes:
import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
import {SafeMath} from "@openzeppelin/contracts/math/SafeMath.sol";
import {Math} from "./Math.sol";
import {MyHelper} from "./helpers/MyHelper.sol";
❌ No:
import {Math} from "./Math.sol";
import {MyHelper} from "./helpers/MyHelper.sol";
import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
import {SafeMath} from "@openzeppelin/contracts/math/SafeMath.sol";
[!TIP] 💡 Grouping and sorting imports by their origin (external vs. internal) and path length keeps the codebase clean and well-organized, facilitating easier dependency management.
Maintain a consistent code layout to improve readability and organization. Structure your code with clear separations between different sections and use proper indentation and spacing.
[!TIP] 💡 A well-organized layout helps developers quickly understand the structure and flow of the code.
Ordering helps readers identify which functions they can call and to find the constructor and fallback definitions easier.
Functions should be grouped according to their visibility and ordered:
Within a grouping, place the view and pure functions last.
✅ Yes:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.7.0 <0.9.0;
contract A {
constructor() {
// ...
}
receive() external payable {
// ...
}
fallback() external {
// ...
}
// External functions
// ...
// External functions that are view
// ...
// External functions that are pure
// ...
// Public functions
// ...
// Internal functions
// ...
// Private functions
// ...
}
❌ No:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.7.0 <0.9.0;
contract A {
// External functions
// ...
fallback() external {
// ...
}
receive() external payable {
// ...
}
// Private functions
// ...
// Public functions
// ...
constructor() {
// ...
}
// Internal functions
// ...
}
[!TIP] 💡 Grouping functions by visibility and type helps maintain a clear and organized contract structure.
Arrange elements in the following order within contracts, libraries, or interfaces:
[!NOTE] This ordering helps readers identify the structure and dependencies of the code more easily.
Inside each contract, library, or interface, use the following order:
[!NOTE] It might be clearer to declare types close to their use in events or state variables.
✅ Yes:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.4 <0.9.0;
abstract contract Math {
error DivideByZero();
function divide(int256 numerator, int256 denominator) public virtual returns (uint256);
}
❌ No:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.8.4 <0.9.0;
abstract contract Math {
function divide(int256 numerator, int256 denominator) public virtual returns (uint256);
error DivideByZero();
}
Each Solidity file should contain only one contract or interface to simplify navigation and improve readability.
[!TIP] 💡 Keeping a single contract or interface per file enhances maintainability and reduces complexity.
Naming conventions are powerful when adopted and used broadly. The use of different conventions can convey significant meta information that would otherwise not be immediately available.
The naming recommendations given here are intended to improve readability, and thus they are not rules, but rather guidelines to try and help convey the most information through the names of things.
Lastly, consistency within a codebase should always supersede any conventions outlined in this document.
Use consistent naming styles to convey the purpose and scope of variables and functions:
b (single lowercase letter)B (single uppercase letter)lowercaseUPPERCASESNAKE_UPPER_CASEPascalCasecamelCase[!NOTE] Consistent naming styles improve readability and help convey meta-information.
[!NOTE] When using initialisms in PascalCase, capitalize all the letters of the initialisms. Thus
HTTPServerErroris better thanHttpServerError. When using initialisms in camelCase, capitalize all the letters of the initialisms, except keep the first one lowercase if it is the beginning of the name. ThusxmlHTTPRequestis better thanXMLHTTPRequest.
Avoid using names that are easily confused with each other or with numerals, such as l, O, and I.
[!NOTE] Using ambiguous names can lead to confusion and errors.
[!CAUTION] 🚨 Never use any of these for single letter variable names. They are often indistinguishable from the numerals one and zero.
SimpleToken, SmartBank, CertificateHashRepository, Player, Congress, Owned.✅ Yes:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.7.0 <0.9.0;
// Owned.sol
contract Owned {
address public owner;
modifier onlyOwner {
require(msg.sender == owner);
_;
}
constructor() {
owner = msg.sender;
}
function transferOwnership(address newOwner) public onlyOwner {
owner = newOwner;
}
}
and in Congress.sol:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.0 <0.9.0;
import "./Owned.sol";
contract Congress is Owned, TokenRecipient {
//...
}
❌ No:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.7.0 <0.9.0;
// owned.sol
contract owned {
address public owner;
modifier onlyOwner {
require(msg.sender == owner);
_;
}
constructor() {
owner = msg.sender;
}
function transferOwnership(address newOwner) public onlyOwner {
owner = newOwner;
}
}
and in Congress.sol:
// SPDX-License-Identifier: GPL-3.0
pragma solidity ^0.7.0;
import "./owned.sol";
contract Congress is owned, tokenRecipient {
//...
}
[!TIP] 💡 Clear and consistent naming of contracts and libraries aids in project organization and readability.
Rule: Interfaces should be named in a way that starts with I followed by the name of the contract it interfaces for, or you can use ContractNameInterface. Whichever naming convention you choose, you should stick to it.
[!NOTE] Consistent naming of interfaces improves readability and helps in distinguishing between contracts and interfaces. This practice makes the code more intuitive and easier to navigate, especially in larger codebases.
Example:
✅ Yes:
interface IToken {
function transfer(address recipient, uint256 amount) external returns (bool);
}
or
interface TokenInterface {
function transfer(address recipient, uint256 amount) external returns (bool);
}
❌ No:
interface token {
function transfer(address recipient, uint256 amount) external returns (bool);
}
Rule: Define all events, errors, structs, and optionally function names within interfaces for better modular organization and clarity.
[!TIP] 💡 Grouping related types within interfaces enhances modularity and clarity, making it easier to manage and understand the structure of contracts.
Example:
✅ Yes:
interface IToken {
struct TokenData {
address issuer;
uint256 value;
}
error Unauthorized();
event TokenIssued(address indexed issuer, uint256 value);
}
// Usage in contract
contract Token is IToken {
// Implementation details
}
❌ No:
contract Token {
struct TokenData {
address issuer;
uint256 value;
}
error Unauthorized();
event TokenIssued(address indexed issuer, uint256 value);
}
Structs should be named using PascalCase to distinguish them from variables and functions.
Examples: MyCoin, Position, PositionXY.
Events should be named using PascalCase and should convey the past tense of an action.
Examples: ContractUpgraded, FundsDeposited.TransferCompleted.
[!NOTE] Clear event names improve the understanding of emitted logs.
Functions should use camelCase. Examples: getBalance, transfer, verifyOwner, addMember, changeOwner.
Variable names should use camelCase and be descriptive to convey their purpose.
Examples: totalSupply, remainingSupply, balancesOf, creatorAddress, isPreSale, tokenExchangeRate.
[!TIP] 💡 Descriptive names help in understanding the code without needing extensive comments.
Function arguments should use camelCase. Examples: initialSupply, account, recipientAddress, senderAddress, newOwner.
When writing library functions that operate on a custom struct, the struct should be the first argument and should always be named self.
Name constants using all uppercase letters with underscores separating words, e.g., MAX_SUPPLY. If a constant is private, prefix it with an underscore.
Examples of public constants:
MAX_BLOCKSTOKEN_NAMETOKEN_TICKERCONTRACT_VERSIONExamples of private constants:
_MAX_BLOCKS_TOKEN_NAME_TOKEN_TICKER_CONTRACT_VERSION[!IMPORTANT] Consistent naming of constants using SNAKE_UPPER_CASE helps in quickly identifying them and prevents accidental modification. This practice enhances code readability and maintainability.
[!TIP] 💡 Prefixing private constants with an underscore
_clarifies their visibility and scope, aiding in code organization and readability.
Modifiers should use camelCase and clearly describe the condition they enforce, e.g., onlyOwner.
Enums should be named using PascalCase and clearly describe their purpose, e.g., UserRole.
Use a single trailing underscore to avoid naming collisions with existing variables, functions, or reserved keywords, e.g., variable_.
[!NOTE] Avoiding naming collisions reduces confusion and potential errors.
[!TIP] 💡 Trailing underscores should be used primarily for parameters or variables that might otherwise collide with reserved keywords, functions, or other variables.
Prefix non-external functions and variables with a single underscore to indicate they are internal or private, e.g., _internalFunction.
[!IMPORTANT] Using an underscore prefix helps differentiate internal/private functions and variables from external ones, improving code clarity.
private or internal). State variables without specified visibility are internal by default.When designing a smart contract, consider the public-facing API (functions callable by any account). Leading underscores help recognize the intent of non-external functions and variables. If you change a function from non-external to external (including public) and rename it, this forces a review of every call site, helping prevent unintended external functions and common security vulnerabilities.
[!TIP] 💡 These conventions aim to create a consistent and readable codebase, making it easier to maintain and understand.
Avoid extraneous whitespace in the following situations:
Immediately inside parentheses, brackets, or braces, with the exception of single-line function declarations.
✅ Yes:
spam(ham[1], Coin({name: "ham"}));
❌ No:
spam( ham[ 1 ], Coin( { name: "ham" } ) );
Exception:
function singleLine() public { spam(); }
Immediately before a comma, semicolon:
✅ Yes:
function spam(uint i, Coin coin) public;
❌ No:
function spam(uint i , Coin coin) public ;
More than one space around an assignment or other operator to align with another:
✅ Yes:
x = 1;
y = 2;
longVariable = 3;
❌ No:
x = 1;
y = 2;
longVariable = 3;
Do not include whitespace in the receive and fallback functions:
✅ Yes:
receive() external payable {
...
}
fallback() external {
...
}
❌ No:
receive () external payable {
...
}
fallback () external {
...
}
[!IMPORTANT] Avoiding unnecessary whitespace in expressions helps maintain clean and readable code.
{ on the same line as the control structure.} on its own line.✅ Yes:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.0 <0.9.0;
contract Coin {
struct Bank {
address owner;
uint balance;
}
}
❌ No:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.0 <0.9.0;
contract Coin
{
struct Bank {
address owner;
uint balance;
}
}
The same recommendations apply to the control structures if, else, while, and for.
Additionally, there should be a single space between the control structures if, while, and for and the parenthetic block representing the conditional, as well as a single space between the conditional parenthetic block and the opening brace.
✅ Yes:
if (...) {
...
}
for (...) {
...
}
❌ No:
if (...)
{
...
}
while(...){
}
for (...) {
...;}
For control structures whose body contains a single statement, omitting the braces is okay if the statement is contained on a single line.
✅ Yes:
if (x < 10)
x += 1;
❌ No:
if (x < 10)
someArray.push(Coin({
name: 'spam',
value: 42
}));
For if blocks that have an else or else if clause, the else should be placed on the same line as the if's closing brace. This is an exception compared to the rules of other block-like structures.
✅ Yes:
if (x < 3) {
x += 1;
} else if (x > 7) {
x -= 1;
} else {
x = 5;
}
if (x < 3)
x += 1;
else
x -= 1;
❌ No:
if (x < 3) {
x += 1;
}
else {
x -= 1;
}
[!TIP] 💡 Consistent formatting of control structures improves readability and helps prevent errors.
✅ Yes:
function increment(uint x) public pure returns (uint) {
return x + 1;
}
function increment(uint x) public pure onlyOwner returns (uint) {
return x + 1;
}
❌ No:
function increment(uint x) public pure returns (uint)
{
return x + 1;
}
function increment(uint x) public pure returns (uint){
return x + 1;
}
function increment(uint x) public pure returns (uint) {
return x + 1;
}
function increment(uint x) public pure returns (uint) {
return x + 1;}
The modifier order for a function should be:
✅ Yes:
function balance(uint from) public view override returns (uint) {
return balanceOf[from];
}
function increment(uint x) public pure onlyOwner returns (uint) {
return x + 1;
}
❌ No:
function balance(uint from) public override view returns (uint) {
return balanceOf[from];
}
function increment(uint x) onlyOwner public pure returns (uint) {
return x + 1;
}
For long function declarations, it is recommended to drop each argument onto its own line at the same indentation level as the function body. The closing parenthesis and opening bracket should be placed on their own line as well at the same indentation level as the function declaration.
✅ Yes:
function thisFunctionHasLotsOfArguments(
address a,
address b,
address c,
address d,
address e,
address f
)
public
{
doSomething();
}
❌ No:
function thisFunctionHasLotsOfArguments(address a, address b, address c,
address d, address e, address f) public {
doSomething();
}
function thisFunctionHasLotsOfArguments(address a,
address b,
address c,
address d,
address e,
address f) public {
doSomething();
}
function thisFunctionHasLotsOfArguments(
address a,
address b,
address c,
address d,
address e,
address f) public {
doSomething();
}
If a long function declaration has modifiers, then each modifier should be dropped to its own line.
✅ Yes:
function thisFunctionNameIsReallyLong(address x, address y, address z)
public
onlyOwner
priced
returns (address)
{
doSomething();
}
function thisFunctionNameIsReallyLong(
address x,
address y,
address z
)
public
onlyOwner
priced
returns (address)
{
doSomething();
}
❌ No:
function thisFunctionNameIsReallyLong(address x, address y, address z)
public
onlyOwner
priced
returns (address) {
doSomething();
}
function thisFunctionNameIsReallyLong(address x, address y, address z)
public onlyOwner priced returns (address)
{
doSomething();
}
function thisFunctionNameIsReallyLong(address x, address y, address z)
public
onlyOwner
priced
returns (address) {
doSomething();
}
Multiline output parameters and return statements should follow the same style recommended for wrapping long lines found in the maximum line length section.
✅ Yes:
function thisFunctionNameIsReallyLong(
address a,
address b,
address c
)
public
returns (
address someAddressName,
uint256 LongArgument,
uint256 Argument
)
{
doSomething();
return (
veryLongReturnArg1,
veryLongReturnArg2,
veryLongReturnArg3
);
}
❌ No:
function thisFunctionNameIsReallyLong(
address a,
address b,
address c
)
public
returns (address someAddressName,
uint256 LongArgument,
uint256 Argument)
{
doSomething();
return (veryLongReturnArg1,
veryLongReturnArg1,
veryLongReturnArg1);
}
For constructor functions on inherited contracts whose bases require arguments, it is recommended to drop the base constructors onto new lines in the same manner as modifiers if the function declaration is long or hard to read.
✅ Yes:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.7.0 <0.9.0;
// Base contracts just to make this compile
contract B {
constructor(uint) {}
}
contract C {
constructor(uint, uint) {}
}
contract D {
constructor(uint) {}
}
contract A is B, C, D {
uint x;
constructor(uint param1, uint param2, uint param3, uint param4, uint param5)
B(param1)
C(param2, param3)
D(param4)
{
// do something with param5
x = param5;
}
}
❌ No:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.7.0 <0.9.0;
// Base contracts just to make this compile
contract B {
constructor(uint) {}
}
contract C {
constructor(uint, uint) {}
}
contract D {
constructor(uint) {}
}
contract A is B, C, D {
uint x;
constructor(uint param1, uint param2, uint param3, uint param4, uint param5)
B(param1)
C(param2, param3)
D(param4) {
x = param5;
}
}
contract X is B, C, D {
uint x;
constructor(uint param1, uint param2, uint param3, uint param4, uint param5)
B(param1)
C(param2, param3)
D(param4) {
x = param5;
}
}
When declaring short functions with a single statement, it is permissible to do it on a single line.
Permissible:
function shortFunction() public { doSomething(); }
[!TIP] 💡 These guidelines for function declarations are intended to improve readability. Authors should use their best judgment as this guide does not try to cover all possible permutations for function declarations.
Do not separate the mapping keyword from its type with a space.
✅ Yes:
mapping(uint => uint) map;
mapping(address => bool) registeredAddresses;
mapping(uint => mapping(bool => Data[])) public data;
mapping(uint => mapping(uint => s)) data;
❌ No:
mapping (uint => uint) map;
mapping( address => bool ) registeredAddresses;
mapping (uint => mapping (bool => Data[])) public data;
mapping(uint => mapping (uint => s)) data;
[!NOTE] Keeping
mappingkeywords without spaces ensures consistent formatting and readability.
Do not add a space between the type and the brackets for array variables.
✅ Yes:
uint[] x;
❌ No:
uint [] x;
[!TIP] 💡 Consistent formatting of variable declarations helps in maintaining readability and avoids confusion.
[!TIP] 💡 Consistent variable declarations prevent confusion and improve readability.
Strings should be quoted with double-quotes instead of single-quotes.
✅ Yes:
string public greeting = "Hello, World!";
❌ No:
string public greeting = 'Hello, World!';
[!NOTE] Using double quotes for strings ensures consistency and aligns with common programming practices.
Surround operators with a single space on either side.
✅ Yes:
x = 3;
x = 100 / 10;
x += 3 + 4;
x |= y && z;
❌ No:
x=3;
x = 100/10;
x += 3+4;
x |= y&&z;
Operators with a higher priority than others can exclude surrounding whitespace in order to denote precedence. This is meant to allow for improved readability for complex statements. You should always use the same amount of whitespace on either side of an operator:
✅ Yes:
x = 2**3 + 5;
x = 2*y + 3*z;
x = (a+b) * (a-b);
❌ No:
x = 2** 3 + 5;
x = y+z;
x +=1;
[!TIP] 💡 Consistent spacing around operators enhances readability and ensures that code is easy to understand.
Solidity contracts can also contain NatSpec comments. They are written with a triple slash (///) or a double asterisk block (/** ... */) and they should be used directly above function declarations or statements.
Example:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >=0.4.16 <0.9.0;
/// @author The Solidity Team
/// @title A simple storage example
contract SimpleStorage {
uint storedData;
/// Store `x`.
/// @param x the new value to store
/// @dev stores the number in the state variable `storedData`
function set(uint x) public {
storedData = x;
}
/// Return the stored value.
/// @dev retrieves the value of the state variable `storedData`
/// @return the stored value
function get() public view returns (uint) {
return storedData;
}
}
It is recommended that Solidity contracts are fully annotated using NatSpec for all public interfaces (everything in the ABI).
[!TIP] 💡 Proper documentation using NatSpec improves code maintainability and usability, especially for public APIs.
[!NOTE] NatSpec should not be used only for public interfaces but also for any function that might be used by other developers, including internal APIs (functions).
Rule: Utilize custom errors instead of require statements for clearer and more gas-efficient error handling. Solidity 0.8.26 supports the use of custom errors with require.
Example:
error InsufficientFunds(uint256 requested, uint256 available);
function withdraw(uint256 amount) public {
if (amount > balance) {
revert InsufficientFunds(amount, balance);
}
balance -= amount;
}
[!TIP] 💡 Custom errors save gas and provide more detailed error messages compared to traditional
requirestrings.
Rule: Use the new require(condition, error) syntax to include custom errors in require statements, available in Solidity 0.8.26 and later.
Example:
error InsufficientFunds(uint256 requested, uint256 available);
function withdraw(uint256 amount) public {
require(amount <= balance, InsufficientFunds(amount, balance));
balance -= amount;
}
[!IMPORTANT] This new syntax provides a more efficient way to handle errors directly within
requirestatements, enhancing both readability and gas efficiency.
Rule: Prefer using custom errors over require with strings for better efficiency. If you must use require with a string message, keep it under 32 bytes to reduce gas costs.
[!IMPORTANT] Custom errors are more gas-efficient and provide clearer error handling. Whenever possible, use them instead of
requirewith a string message.
✅ Yes:
require(balance >= amount, "Insufficient funds");
[!CAUTION] 🚨 Keeping
requiremessages concise (under 32 bytes) minimizes additional gas costs and improves efficiency.
❌ No:
require(balance >= amount, "The balance is insufficient for the withdrawal amount requested.");
[!WARNING] ⚠️ Longer messages significantly increase gas costs. Avoid using verbose messages in
requirestatements.
Rule: Using calldata can significantly reduce gas costs for external functions. It is beneficial for any external function, not just view functions, as long as the parameters are read-only.
✅ Yes:
function totalBalance(address[] calldata accounts) external view returns (uint256 total) {
for (uint i = 0; i < accounts.length; i++) {
total += balances[accounts[i]];
}
}
❌ No:
function totalBalance(address[] memory accounts) external view returns (uint256 total) {
for (uint i = 0; i < accounts.length; i++) {
total += balances[accounts[i]];
}
}
[!TIP] 💡 Using
calldatacan significantly reduce gas costs for external functions. It is beneficial for any external function, not just view functions, as long as the parameters are read-only.
Rule: Cache the length of arrays when used in loop conditions to minimize gas cost.
✅ Yes:
uint length = myArray.length;
for (uint i = 0; i < length; i++) {
// Some logic
}
❌ No:
for (uint i = 0; i < myArray.length; i++) {
// Some logic
}
[!CAUTION] 🚨 Accessing array length multiple times in a loop increases gas costs. Caching the length improves efficiency.
Rule: Use named return arguments for gas efficiency and clarity, especially in functions with multiple return values.
✅ Yes:
function calculate(uint256 a, uint256 b) public pure returns (uint256 sum, uint256 product) {
sum = a + b;
product = a * b;
}
❌ No:
function calculate(uint256 a, uint256 b) public pure returns (uint256, uint256) {
uint256 sum = a + b;
uint256 product = a * b;
return (sum, product);
}
[!TIP] 💡 Named return variables save gas by avoiding redundant return statements and making the code more readable.
Rule: Use named arguments for function calls, events, and errors to improve clarity.
Example:
✅ Yes:
pow({base: x, exponent: y, scalar: v});
❌ No:
pow(x, y, v);
[!IMPORTANT] Explicitly naming arguments improves readability and reduces the chance of errors.
Rule: Explicitly name parameters in mapping types for clarity, especially when nesting is used.
✅ Yes:
mapping(address account => mapping(address asset => uint256 amount)) public balances;
❌ No:
mapping(uint256 => mapping(address => uint256)) public balances;
[!TIP] 💡 Named parameters in mappings make the purpose and usage of the mappings clearer.
Rule: Always declare explicit types for all variable and function return declarations. Avoid using ambiguous types.
✅ Yes:
uint256 public balance;
function getBalance() external view returns (uint256) {}
❌ No:
uint balance = 256; // Use explicit uint256
function getBalance() external view returns (uint) {} // Use explicit uint256
[!TIP] 💡 Using explicit types prevents ambiguity and ensures clarity in your code.
Rule: Internal functions in a library should not have an underscore prefix.
Example:
✅ Yes:
library MathLib {
function add(uint256 a, uint256 b) internal pure returns (uint) {
return a + b;
}
}
using MathLib for uint256;
uint256 result = x.add(y);
❌ No:
library MathLib {
function _add(uint a, uint b) internal pure returns (uint) {
return a + b;
}
}
using MathLib for uint;
uint256 result = x._add(y);
[!IMPORTANT] Internal functions within libraries should be easy to read and follow, avoiding unnecessary prefixes.
Rule: Whenever possible, interact with external contracts through well-defined interfaces. Direct contract calls should be avoided unless they offer specific benefits. If using call, prefer abi.encodeWithSelector to avoid issues.
[!IMPORTANT] Using interfaces for external contract interactions enhances security by ensuring that only defined and expected methods are called, reducing the risk of unexpected behavior. This approach also makes the code more modular and easier to test.
Example:
✅ Yes:
interface IERC20 {
function transfer(address recipient, uint256 amount) external returns (bool);
}
contract MyContract {
IERC20 private _token;
constructor(address tokenAddress) {
_token = IERC20(tokenAddress);
}
function transferToken(address recipient, uint256 amount) public {
_token.transfer(recipient, amount);
}
}
❌ No:
contract MyContract {
address private _tokenAddress;
function transferToken(address recipient, uint256 amount) public {
(bool success, ) = _tokenAddress.call(abi.encodeWithSignature("transfer(address,uint256)", recipient, amount));
require(success, "Transfer failed.");
}
}
Better Approach:
contract MyContract {
address private _tokenAddress;
function transferToken(address recipient, uint256 amount) public {
(bool success, ) = _tokenAddress.call(abi.encodeWithSelector(IERC20.transfer.selector, recipient, amount));
require(success, "Transfer failed.");
}
}
Rule: Prefer custom errors over traditional error messages for better efficiency and clarity.
Naming Convention: Custom error names should follow PascalCase.
Example:
error InsufficientBalance(uint256 requested, uint256 available);
[!TIP] 💡 Use custom errors to save gas and make error handling more descriptive.
Rule: Event names should be in past tense and follow the SubjectVerb format.
Example:
✅ Yes:
event OwnerUpdated(address newOwner);
❌ No:
event OwnerUpdate(address newOwner);
event UpdatedOwner(address newOwner);
[!NOTE] Consistent event naming helps understand contract behavior by reading the emitted events.
Rule: Declare structs, events and errors within their scope. If a struct or error is used across many files, define them in their own file. Multiple structs and errors can be defined together in one file.
[!TIP] 💡 Centralize common structures, events and errors to improve maintainability and clarity.
Rule: For upgradeable contracts, use the ERC-7201 "Namespaced Storage Layout" convention. It groups storage variables under a keccak-derived slot far from slot 0, eliminating collisions across inheritance chains and proxy upgrades.
The namespace slot is computed as:
keccak256(abi.encode(uint256(keccak256(bytes(id))) - 1)) & ~bytes32(uint256(0xff))
Annotate the storage struct with @custom:storage-location erc7201:<namespace> so tooling (Solidity compiler, OpenZeppelin upgrades, audit linters) can detect it.
✅ Yes:
// SPDX-License-Identifier: MIT
pragma solidity 0.8.34;
contract Vault {
/// @custom:storage-location erc7201:myapp.storage.Vault
struct VaultStorage {
mapping(address account => uint256 amount) balances;
uint256 totalDeposited;
}
// keccak256(abi.encode(uint256(keccak256("myapp.storage.Vault")) - 1)) & ~bytes32(uint256(0xff))
bytes32 private constant _VAULT_STORAGE_SLOT =
0xb0b7f08e6b72da11d79f0fae1b47752dd69f3b7f0a08dfe33b0a9a7e3c7b3a00;
function _getVaultStorage() private pure returns (VaultStorage storage $) {
bytes32 slot = _VAULT_STORAGE_SLOT;
assembly { $.slot := slot }
}
function deposit(uint256 amount) external {
VaultStorage storage $ = _getVaultStorage();
$.balances[msg.sender] += amount;
$.totalDeposited += amount;
}
}
❌ No:
// SPDX-License-Identifier: MIT
pragma solidity 0.8.34;
contract Vault {
// Plain slot-0 storage (will collide with parent contracts in a proxy).
mapping(address => uint256) public balances;
uint256 public totalDeposited;
}
[!IMPORTANT] Precompute the slot constant with a build-time helper (
cast keccak, a small Foundry script, or OpenZeppelin's@custom:storage-locationtooling) and commit the literal value. Recomputing it at runtime wastes gas and prevents the compiler from hard-coding it.
Rule: Transient storage (tstore / tload, EIP-1153) is available from Solidity 0.8.24 and provides per-transaction scratch space that costs far less than SSTORE / SLOAD. It is ideal for reentrancy locks, temporary flags, and call-graph metadata. Requires the Cancun EVM target or later; Solidity 0.8.34 defaults to Prague.
✅ Yes (reentrancy lock on transient storage):
// SPDX-License-Identifier: MIT
pragma solidity 0.8.34;
abstract contract TransientReentrancyGuard {
// bytes32(uint256(keccak256("eip1967.reentrancy.slot")) - 1)
bytes32 private constant _LOCK_SLOT = 0xa8a2...;
error Reentrancy();
modifier nonReentrant() {
assembly {
if tload(_LOCK_SLOT) { revert(0, 0) }
tstore(_LOCK_SLOT, 1)
}
_;
assembly { tstore(_LOCK_SLOT, 0) }
}
}
[!WARNING] ⚠️ Transient storage is cleared at the end of the transaction, not the call. It is not a replacement for regular storage and must not be used to hold state that must outlive the tx.
Rule: Avoid unnecessary version pragma constraints. While main contracts should specify a single Solidity version, supporting contracts and libraries should have as open a pragma as possible.
✅ Yes:
pragma solidity ^0.8.0;
❌ No:
pragma solidity ^0.8.0 ^0.9.0;
[!TIP] 💡 Use open pragmas for supporting contracts and libraries to enhance compatibility and flexibility.
Rule: Use inline assembly with extreme care. Ensure that it is well-documented with inline comments explaining what the assembly code does. Avoid using assembly unless it adds significant value and there are no better alternatives.
Example:
function add(uint x, uint y) public pure returns (uint result) {
assembly {
// Add x and y and store the result in the `result` variable
result := add(x, y)
}
}
[!WARNING] ⚠️ Assembly code is hard to read and audit, increasing the risk of errors and vulnerabilities. Use it only when necessary and ensure thorough documentation to maintain code clarity and security.
[!CAUTION] 🚨 Avoid using assembly if it does not provide significant performance or functional benefits. Always prefer high-level Solidity when possible.
Rule: Prefer defining functions as part of a larger contract rather than creating many small contracts.
[!NOTE] Inheritance is useful but should be used judiciously, especially when building on existing, trusted contracts like
Ownablefrom OpenZeppelin.
Foundry provides a flexible and efficient framework for structuring your tests. Here are the recommended structures:
Unit Tests
contract Add, contract Supply.contract MyContractTest.contract Add {
function test_add_AddsTwoNumbers() public {
// Test code
}
}
contract MyContractTest {
function test_add_AddsTwoNumbers() public {
// Test code
}
function test_supply_UsersCanSupplyTokens() public {
// Test code
}
}
Integration Tests
[!TIP] 💡 Organizing tests logically improves maintainability and makes it easier to identify and fix issues.
Test Coverage
test_Description for standard tests.testFuzz_Description for fuzz tests.function test_transfer() public {
// Test code
}
function testFuzz_transfer(uint amount) public {
// Test code
}
Test Naming Conventions
function test_RevertIf_Condition() public {
// Test code expecting revert
}
function testForkFuzz_RevertIf_Condition() public {
// Fuzz test with fork expecting revert
}
[!NOTE] Consistent naming aids in test management and improves readability.
setUp function. Instead, use a dedicated test like test_SetUpState.[!IMPORTANT] Isolating setup logic from assertions ensures clarity and reduces potential errors.
Utilize mocking and stubbing to simulate complex interactions and dependencies.
Example:
contract MockContract {
function mockedFunction() public returns (bool) {
return true;
}
}
[!TIP] 💡 Mocking and stubbing help in testing functionalities in isolation.
Foundry supports property-based testing to ensure that your contracts hold certain properties over a wide range of inputs.
Example:
function test_property(uint x) public {
assert(x < 1000);
}
Monitor and optimize gas usage by incorporating gas usage tests.
Example:
function testGasUsage() public {
uint gasStart = gasleft();
// Function call
uint gasUsed = gasStart - gasleft();
emit log_named_uint("Gas used: ", gasUsed);
}
[!CAUTION] 🚨 Regular gas usage tests help in optimizing smart contract efficiency.
Fuzz Testing
function testFuzz(uint x) public {
// Fuzz test code
}
Debugging with Foundry
function testDebug() public {
// Debug test code
}
[!TIP] 💡 Leveraging Foundry's tools and utilities enhances test coverage and debugging capabilities.
MyContract.sol, the test file should be MyContract.t.sol.MyContract.owner.t.sol, MyContract.deposits.t.sol.setUp; use dedicated tests.[!NOTE] Consistent file naming and structure make it easier to locate and manage tests.
These practices and tools ensure comprehensive and efficient testing, leveraging Foundry's capabilities to maintain robust and reliable smart contracts.
Optimizing gas usage is crucial for efficient and cost-effective smart contracts. Here are some best practices:
calldata for function parameters.immutable or constant where possible to save gas.uint256: Using uint256 over smaller types like uint8 or uint32 can be more gas efficient due to padding.Example:
uint immutable public value; // Immutable variable
uint[] public data;
function optimizedFunction(uint[] calldata input) external {
uint length = input.length; // Cache array length
for (uint i = 0; i < length; i++) {
data.push(input[i]);
}
}
Security is paramount in smart contract development. Adhere to the following best practices to mitigate common vulnerabilities:
Reentrancy attacks occur when a contract calls an external contract before updating its state, allowing the external contract to call back into the original contract and manipulate its state. Prevent reentrancy by:
Example:
bool private locked;
modifier noReentrant() {
require(!locked, "Reentrant call");
locked = true;
_;
locked = false;
}
function withdraw(uint amount) external noReentrant {
require(balances[msg.sender] >= amount, "Insufficient balance");
balances[msg.sender] -= amount;
(bool success, ) = msg.sender.call{value: amount}("");
require(success, "Transfer failed");
}
[!WARNING] ⚠️ Always perform state updates before calling external contracts to prevent reentrancy attacks.
Ensure proper access control mechanisms are in place:
onlyOwner Modifiers: Restrict critical functions to the contract owner or specific roles.Example:
address public owner;
mapping(address => bool) public admins;
modifier onlyOwner() {
require(msg.sender == owner, "Not owner");
_;
}
modifier onlyAdmin() {
require(admins[msg.sender], "Not admin");
_;
}
function addAdmin(address admin) external onlyOwner {
admins[admin] = true;
}
[!TIP] 💡 Use libraries like OpenZeppelin's Access Control for robust access management.
Prevent integer overflow and underflow by:
SafeMath library for safe arithmetic operations.Example:
using SafeMath for uint256;
function safeAdd(uint256 a, uint256 b) public pure returns (uint256) {
return a.add(b);
}
[!CAUTION] 🚨 Always use safe arithmetic operations to prevent unexpected overflows and underflows.
Handle Ether transfers securely by:
call instead of transfer or send: call provides more flexibility and forwards all available gas.call.Example:
function safeTransfer(address payable recipient, uint256 amount) internal {
(bool success, ) = recipient.call{value: amount}("");
require(success, "Transfer failed");
}
[!IMPORTANT] Properly handle Ether transfers to avoid vulnerabilities related to gas limits and failed transfers.
Regular code reviews and security audits are essential for identifying and mitigating potential vulnerabilities:
[!TIP] 💡 Regularly update and audit your contracts, especially after significant changes or before deployment.
By following these best practices, you can enhance the performance, security, and robustness of your Solidity smart contracts.
Every modern code editor and agent has a canonical context file here, so you can point your tools at this repo and they will load the rules automatically:
Install the bundled skill once, then ask the agent to review or apply the guide on any Solidity repo.
# Project-scoped
mkdir -p .claude/skills
cp -r skill .claude/skills/solidity-style-guide
# Or global
mkdir -p ~/.claude/skills
cp -r skill ~/.claude/skills/solidity-style-guide
Then inside Claude Code:
/solidity-style-guide:review # audit without editing
/solidity-style-guide:review --fix # apply minimal formatting / naming diffs
/solidity-style-guide:apply-config # copy solhint/prettier/editorconfig
These agents pick up AGENTS.md and .cursorrules automatically when opened in a workspace. No install step.
Pointing any LLM-backed tool at https://raw.githubusercontent.com/Aboudjem/solidity-style-guide/main/llms.txt gives it a machine-friendly index of the rules, configs, and companion docs.
[!TIP] The style guide ships the same rules in three surfaces: the README (for humans), the Claude Code skill (for agents), and
AGENTS.md(for any tool). They are kept in sync by the PR template checklist.
Short, source-cited answers to the questions developers ask most often about this Solidity style guide.
What Solidity version does this guide target?
0.8.34. Pin it for application contracts (pragma solidity 0.8.34;) and use an open range ^0.8.20 for libraries and mixins. Version 0.8.34 ships with the Prague EVM as default in light of the May 2025 Pectra upgrade.
When should I use require(cond, CustomError()) vs revert CustomError()?
Use require(cond, CustomError()) on Solidity ≥ 0.8.26 with via-IR or ≥ 0.8.27 on the legacy pipeline. On older versions, use the if (!cond) revert CustomError(...); pattern. Both are cheaper than require(cond, "string").
Why ERC-7201 namespaced storage?
ERC-7201 prevents storage collisions in upgradeable contracts and in contracts that use inheritance heavily. The namespace is rooted at keccak256(abi.encode(uint256(keccak256(bytes(id))) - 1)) & ~bytes32(uint256(0xff)), which keeps it far from slot 0. Annotate the struct with /// @custom:storage-location erc7201:<namespace>.
Do I still need unchecked { ++i; } in for-loops?
Since Solidity 0.8.22 the compiler hoists ++i increments into an unchecked block automatically when overflow is infeasible, so the manual pattern is no longer required for simple counters. Keep unchecked for custom arithmetic where you've reasoned about bounds yourself.
Should I use uint256 or smaller uints to save gas?
uint256. Smaller types cost more gas individually because the EVM word size is 256 bits. Use smaller types only when packing several values into a single storage slot.
Named imports: required or recommended?
Required. import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol"; documents intent and lets tooling catch unused imports. Wildcard imports import "./X.sol"; pull every symbol and hurt readability.
What testing framework does this guide assume?
Foundry. The testing section uses Foundry's naming matrix: test_Description, testFuzz_Description, test_RevertWhen_Description, testFork_Description, invariant_Property. Most rules translate to Hardhat but the naming conventions do not.
How is this different from the official Solidity style guide?
The official guide covers syntax and formatting only. This guide extends it with best practices (custom errors, named returns, explicit types), gas patterns, security patterns, Foundry testing conventions, NatSpec guidance, ERC-7201 storage, transient storage, and a Claude Code skill that applies the rules across a codebase.
Can I use this guide in a commercial project?
Yes. MIT licensed, see LICENSE.
How do I propose a new rule?
Open an issue with the rule proposal template or a PR. Each rule needs a name, rationale, a ✅ Yes example, a ❌ No example, and an authoritative source. See CONTRIBUTING.md.
This Solidity Style Guide extends the official guidelines with practical rules for modern Solidity: custom errors, named imports, ERC-7201 namespaced storage, transient storage, Foundry testing, gas patterns, and security. It ships with Solhint and Prettier configs, a GitHub Actions CI workflow, and a Claude Code skill that applies the rules across any codebase.
Primary sources
This guide supplements, rather than replaces, the official style guide. Contributions are welcome. See CONTRIBUTING.md. Security-relevant corrections go through SECURITY.md.
Connect
Happy shipping. Clean Solidity is cheap Solidity is safe Solidity.
Claude Code skill for YouTube creators — channel audits, video SEO, retention scripts, thumbnails, content strategy, Sho
AI image generation skill for Claude Code -- Creative Director powered by Gemini
A Claude Code skill by Hao (駱君昊) that learns your Facebook voice and auto-posts to FB / IG / Threads / X with a 14-day c
Universal SEO skill for Claude Code. 25 sub-skills + 18 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, bac