Naming Conventions

Introduction

Consistent naming improves discoverability, maintainability, and collaboration. These conventions apply to all Cowboy documentation, code, and assets.

Rule: When in doubt, use kebab-case for files and snake_case for code

File Naming

Documentation Files (.mdx)

Format: kebab-case.mdx Rules (short):

Lowercase; use hyphens between words
Be descriptive; avoid overly generic names

Examples:

✅ actor-vm-overview.mdx
✅ dual-eip1559.mdx
❌ ActorVMOverview.mdx
❌ overview.mdx

Diagram Files

Format: category-description.[svg|mmd|excalidraw|drawio] Examples:

✅ architecture-system-overview.svg
✅ sequence-message-flow.mmd
❌ diagram1.svg

Image Files

Format: kebab-case.[png|jpg|svg] Examples:

✅ logo-dark.png
✅ validator-dashboard.png
❌ Logo.png
❌ screenshot_1.png

Directory Naming

Documentation Directories

Format: kebab-case/ (match existing IA) Examples:

✅ architecture/
✅ getting-started/
✅ offchain/
❌ Architecture/
❌ getting_started/

Code Naming (Python)

Files

Format: snake_case.py

✅ token_actor.py
❌ TokenActor.py

Classes

Format: PascalCase

✅ class TokenActor(Actor)
❌ class token_actor(Actor)

Functions/Methods

Format: snake_case

✅ def get_balance(self, address)
❌ def GetBalance(...)

Variables

Format: snake_case (constants use UPPER_SNAKE_CASE)

✅ user_balance = 100
✅ MAX_GAS_LIMIT = 10_000_000
❌ totalSupply

Terminology Standards

Cowboy-Specific Terms

Always Use (capitalized when referring to Cowboy concepts):

Concept	✅ Correct	❌ Avoid
Compute unit	Actor	contract, smart contract
Off-chain worker	Runner	oracle, worker
Compute gas	Cycles	gas, compute
Data gas	Cells	bytes, data
Native token	CBY	Cowboy, token

Abbreviations (minimal)

Use common, project-wide forms (see Style Guide): VM, API, SDK, CLI, CBY, PoS, DoS, CIP.

API Endpoints

Format: /api/v1/resource-name

✅ /api/v1/validators/status
❌ /api/v1/Actors/... 

Quick Reference Table

Context	Convention	Example
Documentation files	kebab-case.mdx	`actor-vm-overview.mdx`
Diagram files	category-name.svg	`architecture-overview.svg`
Python files	snake_case.py	`token_actor.py`
Python classes	PascalCase	`class TokenActor`
Python functions	snake_case	`def transfer()`
Python constants	UPPER_SNAKE_CASE	`MAX_CYCLES`
Directories	kebab-case/	`getting-started/`
URLs	/kebab-case	`/architecture/actor-vm`
Git commits	type: description	`docs: add guide`
Git branches	type/issue-desc	`feat/123-new-api`
Version tags	vX.Y.Z	`v0.1.0`

This v0.1 guide focuses on the essentials to keep contributions fast and consistent. We will expand with edge cases in later milestones.

Introduction

Overview

Whitepaper

Getting Started

Architecture

Security

Economics

Ethereum Interoperability

Developer Guide

Protocol Specifications

Style & Documentation

Contributing

Versioning & Updates

References

Open Design Questions

Introduction

File Naming

Documentation Files (.mdx)

Diagram Files

Image Files

Directory Naming

Documentation Directories

Code Naming (Python)

Files

Classes

Functions/Methods

Variables

Terminology Standards

Cowboy-Specific Terms

Abbreviations (minimal)

API Endpoints

Quick Reference Table

​Introduction

​File Naming

​Documentation Files (.mdx)

​Diagram Files

​Image Files

​Directory Naming

​Documentation Directories

​Code Naming (Python)

​Files

​Classes

​Functions/Methods

​Variables

​Terminology Standards

​Cowboy-Specific Terms

​Abbreviations (minimal)

​API Endpoints

​Quick Reference Table

Introduction

File Naming

Documentation Files (.mdx)

Diagram Files

Image Files

Directory Naming

Documentation Directories

Code Naming (Python)

Files

Classes

Functions/Methods

Variables

Terminology Standards

Cowboy-Specific Terms

Abbreviations (minimal)

API Endpoints

Quick Reference Table