CODE_STYLE.md

Code Style

This document defines the official coding standards for all CeloHT repositories.

Consistent code improves readability, maintainability, collaboration, and long-term sustainability across the CeloHT ecosystem.

---

Philosophy

Every line of code should be:

• Simple
• Readable
• Maintainable
• Secure
• Well documented
• Tested

Code is written for people first, computers second.

---

General Principles

Always:

• Write self-explanatory code.
• Keep functions small.
• Avoid duplicated logic.
• Prefer composition over complexity.
• Follow SOLID principles.
• Keep files organized.
• Remove dead code.

---

Naming Conventions

Variables

Use descriptive camelCase names.

Good

const walletAddress
const courseProgress
const verifiedAgent

Bad

const wa
const data
const x

---

Constants

Use UPPER_SNAKE_CASE.

const MAX_RETRY_COUNT = 3

const DEFAULT_NETWORK = "celo"

---

Functions

Use camelCase.

connectWallet()

createProposal()

verifyCertificate()

Function names should describe an action.

---

Classes

Use PascalCase.

WalletService

EducationManager

AgentRegistry

---

Interfaces

Prefix with I only if required by the repository standard.

Example

Wallet

Agent

EducationCourse

---

React Components

Use PascalCase.

HeroSection.tsx

EducationCard.tsx

Navbar.tsx

---

File Naming

Use kebab-case unless framework conventions require otherwise.

Examples

wallet-service.ts

education-api.ts

agent-utils.ts

React components

HeroSection.tsx

Footer.tsx

---

Folder Structure

Example

components/

hooks/

services/

utils/

contracts/

types/

docs/

scripts/

Every folder should have a clear responsibility.

---

Formatting

Official formatter:

• Prettier

Never manually fight the formatter.

Run

npm run format

before submitting a Pull Request.

---

Linting

Official linter:

• ESLint

Run

npm run lint

Every Pull Request must pass linting.

---

TypeScript

Use strict typing whenever possible.

Avoid

any

Prefer

interface

type

unknown

generics

---

Functions

Functions should:

• Do one thing.
• Be short.
• Return predictable results.
• Handle errors appropriately.

Avoid extremely long functions.

---

Comments

Write comments only when necessary.

Prefer

calculateTreeImpact()

instead of

// Calculates tree impact

Good code should explain itself.

---

Error Handling

Always handle errors gracefully.

Example

try {

    await wallet.connect()

} catch (error) {

    console.error(error)

}

Never silently ignore errors.

---

Imports

Group imports.

Example

// External

import React from "react"

import { ethers } from "ethers"

// Internal

import WalletButton from "@/components/WalletButton"

import { connectWallet } from "@/lib/wallet"

Remove unused imports.

---

Smart Contracts

Solidity contracts should:

• Follow OpenZeppelin standards.
• Include NatSpec documentation.
• Use events appropriately.
• Validate all inputs.
• Minimize gas usage.
• Include automated tests.

---

Documentation

Every public function should include documentation when appropriate.

Example

/**
 * Connects the user's wallet.
 */

---

Commit Style

Use Conventional Commits.

Examples

feat:

fix:

docs:

refactor:

test:

style:

perf:

build:

ci:

chore:

Example

feat: add governance dashboard

docs: update installation guide

fix: resolve wallet connection bug

---

Pull Requests

A Pull Request should:

• Solve one problem.
• Include documentation updates.
• Pass all tests.
• Follow the style guide.
• Be reviewed before merging.

---

Security

Never commit:

• Private keys
• Recovery phrases
• API secrets
• Passwords
• Tokens
• Database credentials

Secrets belong only in environment variables.

---

Accessibility

Frontend code should:

• Use semantic HTML.
• Support keyboard navigation.
• Include ARIA labels where needed.
• Maintain sufficient color contrast.
• Work on desktop and mobile devices.

---

Performance

Developers should:

• Avoid unnecessary renders.
• Reduce bundle size.
• Optimize images.
• Lazy-load heavy components.
• Profile performance before optimizing.

---

Code Review Checklist

Before requesting review, verify:

• Code is readable.
• Tests pass.
• Lint passes.
• Documentation updated.
• No secrets committed.
• No unnecessary dependencies.
• No duplicated logic.

---

Future Improvements

The coding standards will continue evolving as the CeloHT ecosystem grows.

All contributors are encouraged to propose improvements through GitHub Discussions or Pull Requests.

---

Conclusion

Consistent coding standards strengthen collaboration, improve maintainability, and help ensure that every CeloHT repository remains secure, scalable, and welcoming to contributors from around the world.