kyzooghost/developing-smart-contracts

Smart Contract Development

Best practices for developing Solidity smart contracts. Contains rules covering documentation, naming, structure, and code style.

When to Apply

Reference these guidelines when:

• Writing new Solidity contracts
• Reviewing smart contract code
• Refactoring existing contracts
• Adding NatSpec documentation
• Setting up contract file structure

Licenses

• Interfaces: // SPDX-License-Identifier: Apache-2.0
• Contracts: // SPDX-License-Identifier: AGPL-3.0

Rule Categories by Priority

| Priority | Category | Impact | Rule File | | -------- | -------------- | -------- | ------------------------ | | 1 | NatSpec | CRITICAL | rules/natspec.md | | 2 | File Layout | HIGH | rules/file-layout.md | | 3 | Naming | HIGH | rules/naming-conventions.md | | 4 | Imports | MEDIUM | rules/imports.md | | 5 | Visibility | MEDIUM | rules/visibility.md | | 6 | General Rules | LOW | rules/general-rules.md |

Quick Reference

1. NatSpec Documentation (CRITICAL)

ALWAYS use NatSpec for all public/external items.

• Every public/external function MUST have @notice
• Every parameter MUST have @param _paramName (in signature order)
• Every return value MUST have @return variableName
• Events MUST document all parameters
• Errors MUST explain when they are thrown

See rules/natspec.md for examples.

2. File Layout (HIGH)

Interface structure:

1. Structs → 2. Enums → 3. Events → 4. Errors → 5. External Functions

Contract structure:

1. Constants → 2. State variables → 3. Structs → 4. Enums → 5. Events → 6. Errors → 7. Modifiers → 8. Functions

See rules/file-layout.md for templates.

3. Naming Conventions (HIGH)

| Item | Convention | Example | | ----------------------- | ---------------- | -------------------------------- | | Public state | camelCase | uint256 messageCount | | Private/internal state | _camelCase | uint256 _internalCounter | | Constants | UPPER_SNAKE_CASE | bytes32 DEFAULT_ADMIN_ROLE | | Function params | _camelCase | function send(address _to) | | Return variables | camelCase | returns (bytes32 messageHash) | | Mappings | descriptive keys | mapping(uint256 id => bytes32) | | Init functions | __Contract_init | __PauseManager_init() |

See rules/naming-conventions.md for details.

4. Imports (MEDIUM)

Always use named imports:

// CORRECT
import { IMessageService } from "../interfaces/IMessageService.sol";

// WRONG
import "../interfaces/IMessageService.sol";

See rules/imports.md for details.

5. Visibility (MEDIUM)

• Constants: internal unless explicitly needed public
• Functions: Minimize external/public surface area
• Avoid this.functionCall() pattern

See rules/visibility.md for details.

6. General Rules (LOW)

• Avoid magic numbers: Use named constants
• Assembly: Use hex for memory offsets
• Linting: Run pnpm run lint:fix before committing

See rules/general-rules.md for deployment, testing, and more.

PR Checklist

Before submitting a PR:

• [ ] All public items have NatSpec (@notice, @param, @return)
• [ ] Named imports used
• [ ] Naming conventions followed
• [ ] Constants are internal unless needed public
• [ ] Linting passes (pnpm run lint:fix)
• [ ] No magic numbers

How to Use

Read individual rule files for detailed explanations and code examples:

rules/natspec.md
rules/file-layout.md
rules/naming-conventions.md

Each rule file contains:

• Explanation of why the rule matters
• Incorrect code example
• Correct code example

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md