The following is a style-guide for the Huff-Std library. Feedback and discussion is welcome.

Formatting

Lines should be no greater than 100 characters (disregarding long constant names/values).

Files should use 4 spaces for indentions.

File Structure

The file structure of a Huff contract so follow this:

/* Imports */
#include "./contracts/utils/ExampleImport1.huff"
#include "./contracts/utils/ExampleImport2.huff"

/* Function Interfaces */
#define function exampleFunction1(address,uint256) nonpayable returns ()
#define function exampleFunction2(address,uint256) nonpayable returns ()

#define function exampleFunction3(address,address,uint256) nonpayable returns ()
#define function exampleFunction4(address,uint256) nonpayable returns ()

#define event ExampleEvent1(address indexed example)
#define event ExampleEvent2(address indexed example)

/* Events Signatures */
#define constant EXAMPLE_EVENT_SIGNATURE1 = 0xDDF252AD1BE2C89B69C2B068FC378DAA952BA7F163C4A11628F55A4DF523B3EF
#define constant EXAMPLE_EVENT_SIGNATURE2 = 0x8C5BE1E5EBEC7D5BD14F71427D1E84F3DD0314C0F7B2291E5B200AC8C7C3B925

/* Storage Slots */
#define constant EXAMPLE_SLOT1 = FREE_STORAGE_POINTER()
#define constant EXAMPLE_SLOT2 = FREE_STORAGE_POINTER()
#define constant EXAMPLE_SLOT3 = FREE_STORAGE_POINTER()

/* Constructor */
#define macro CONSTRUCTOR() = takes(0) returns (0) {}

/* Macros */
#define macro MYMAC() = takes (0) returns (0) {}

/* Entry Point */
#define macro MAIN() = takes (0) returns (0) {}

The next aspect of this is more complicated, because it depends on the context and functionality of the contract. Essentially, we want to categorize macros into sections based on their functionality. Here is an example from an existing ERC20 contract:

/* Accounting Macros */
#define macro BALANCE_OF() = takes (0) returns (0) {}
#define macro TOTAL_SUPPLY() = takes (0) returns (0) {}
#define macro ALLOWANCE() = takes (0) returns (0) {}

/* Transfer Macros */
#define macro TRANSFER_TAKE_FROM(error) = takes(3) returns (3) {}
#define macro TRANSFER_GIVE_TO() = takes(3) returns (0) {}
#define macro TRANSFER() = takes(0) returns(1) {}

/* Approval Macros */
#define macro APPROVE() = takes (0) returns (0) {}

/* Mint Macros */
#define macro MINT() = takes(0) returns (0) {}

Code Comments

Comments should use the double slash (//) syntax, unless they are used to mark a new section of the codebase (see above).

Comments describing the functionality of a statement, macro, etc should be on the line(s) prior.

// owner slot
#define constant OWNER_SLOT = FREE_STORAGE_POINTER()

Comments indicating the stack after an instruction should be on the right of the instruction. Instruction comments within the same code block should be aligned vertically with the right-most instruction comment. The right-most instruction comment should be one “tab” from

0x20    // [value]
0x00    // [offset, value]
mstore  // []

Macro Definition

Macros with a non-zero takes expectation should include a single comment at the start of the code block indicating the expected stack in the following format.