Skip to main content

Solidity Style Guide

Primitive Solidity smart-contracts are mainly following the official Solidity style guide, however this guide extends the official one by adding some extra and specific rules.

Additionally, our repositories are using Prettier with Prettier Solidity plugin.

note

In case of conflicting rules between the official and the Primitive Solidity style guide, this one must always prevail.

Folder Structure

All the repositories must have the following folder structure:

project/
├─ contracts/
│ ├─ interfaces/
│ │ ├─ external/
│ ├─ libraries/
│ ├─ test/
├─ test/

Versioning

Contracts and libraries must have a locked pragma with (ideally) the latest Solidity version.

pragma solidity 0.8.13;

Interfaces can have a lower version to insure a maximum compatibility.

pragma solidity >=0.8.0;

Naming Conventions

TypeFormatExample
mutable variables, public or external functionsSnake casemyVariable
constant variablesUpper caseMY_CONSTANT
internal or private functionsSnake case starting with an underscore_internalStuff
constructor parametersSnake case ending with an underscoreowner_

Licensing

All the files and repositories must include one of the following licenses GPL, MIT or be marked as UNLICENSED.

// SPDX-License-Identifier: GPL-3.0-only

Commenting

All the Solidity code must have explicit comments and proper documentation using the NatSpec format. All the NatSpec tags can be used to describe contracts, interfaces, librarires, structs, functions, variables, etc...

/// @title   PrimitiveManager contract
/// @author Primitive
/// @notice Interacts with Primitive Engine contracts

Extra spaces should be added between the tag and the comment to give this specific style:

/// @param factory_             Address of a PrimitiveFactory
/// @param WETH9_ Address of WETH9
/// @param positionDescriptor_ Address of PositionDescriptor

Custom tags can be used to add extra details:

/// @notice Single instruction processor that will forward instruction to appropriate function.
/// @dev Critical: Every token of every pair interacted with is cached to be settled later.
/// @param data Encoded Enigma data. First byte must be an Enigma instruction.
/// @custom:security Critical. Directly sends instructions to be executed.

Different declarations within the code can be separated using the following titles:

/// ERRORS ///

...

/// EVENTS ///

...

/// STATE VARIABLES ///

...

/// EFFECT FUNCTIONS ///

...

/// VIEW FUNCTIONS ///

...

/// PRIVATE FUNCTIONS ///

...