Skip to main content

Naming Conventions

Standard naming conventions used across all EGI systems. Consistent naming improves discoverability, reduces confusion, and makes systems easier to maintain.

Quick Reference

When in doubt, use kebab-case for URLs and files, camelCase for code, and descriptive-names over abbreviations.

General Principles​

  1. Be Descriptive: Names should clearly indicate purpose
  2. Be Consistent: Follow established patterns
  3. Be Concise: Avoid unnecessary words, but don't sacrifice clarity
  4. Avoid Abbreviations: Unless widely understood (API, URL, etc.)
  5. Use English: All names should be in English

Repositories​

Format​

[product]-[type]-[variant]

Rules​

  • Use kebab-case (lowercase with hyphens)
  • Start with product/project name
  • Include repository type (web, api, docs, etc.)
  • Add variant if multiple similar repos exist

Examples​

Good:

  • company-website
  • client-portal-api
  • internal-docs
  • egi-sop-docs
  • fpd-dashboard-web
  • erp-integration-service

Bad:

  • Website (not kebab-case)
  • proj1 (not descriptive)
  • the-new-api (meaningless qualifier)
  • temp_repo (underscore instead of hyphen)

Special Prefixes​

  • archived-* - Archived/deprecated repositories
  • poc-* - Proof of concept projects
  • template-* - Template repositories

Git Branches​

Main Branches​

  • main - Primary production branch
  • develop - Development integration branch (if using Git Flow)
  • staging - Staging environment branch (if separate from main)

Feature Branches​

feature/short-description

Examples:

  • feature/user-authentication
  • feature/payment-integration
  • feature/csv-export

Bug Fix Branches​

bugfix/issue-description

Examples:

  • bugfix/login-redirect-loop
  • bugfix/email-validation
  • bugfix/broken-api-endpoint

Hotfix Branches​

hotfix/critical-issue

For urgent production fixes:

  • hotfix/security-vulnerability
  • hotfix/payment-processor-down

Release Branches​

release/v1.2.0

For preparing releases:

  • release/v1.0.0
  • release/v2.1.0

Other Branch Types​

docs/what-changed
refactor/component-restructure
test/add-integration-tests
chore/update-dependencies

Commit Messages​

Format (Conventional Commits)​

type(scope): description

[optional body]

[optional footer]

Types​

  • feat - New feature
  • fix - Bug fix
  • docs - Documentation only
  • style - Formatting, missing semicolons, etc.
  • refactor - Code restructuring without changing behavior
  • perf - Performance improvement
  • test - Adding or updating tests
  • chore - Maintenance tasks, dependency updates
  • ci - CI/CD configuration changes
  • build - Build system changes

Examples​

Good:

feat(auth): add OAuth2 integration

Implemented Google and GitHub OAuth providers.
Includes login/logout flows and session management.

Closes #123
fix(api): resolve null pointer in user endpoint

Added null check before accessing user.profile.
docs: update deployment instructions

Bad:

Updated stuff
Fixed bug
WIP
asdf

Pull Requests​

Title Format​

[Type] Brief description

Examples​

Good:

  • [Feature] Add user dashboard
  • [Fix] Resolve login redirect issue
  • [Docs] Update API documentation
  • [Refactor] Reorganize authentication module

Bad:

  • Updates (not descriptive)
  • PR (meaningless)
  • Fix everything (too vague)

Description Requirements​

Every PR should include:

  • What changed
  • Why it changed
  • How to test
  • Screenshots (if UI changes)
  • Related issues/tickets

Environment Variables​

Format​

COMPONENT_CATEGORY_NAME

Rules​

  • Use SCREAMING_SNAKE_CASE (uppercase with underscores)
  • Start with component/service name
  • Group related variables with common prefixes
  • Be explicit about purpose

Examples​

Good:

# Database
DATABASE_URL
DATABASE_POOL_SIZE
DATABASE_SSL_ENABLED

# API
API_BASE_URL
API_KEY
API_TIMEOUT_MS

# Email
EMAIL_SMTP_HOST
EMAIL_SMTP_PORT
EMAIL_FROM_ADDRESS

# Feature Flags
FEATURE_NEW_DASHBOARD_ENABLED
FEATURE_BETA_ACCESS_ENABLED

# Third-party Services
STRIPE_API_KEY
STRIPE_WEBHOOK_SECRET
POSTHOG_API_KEY

Bad:

dburl (not descriptive enough)
APIKEY (missing underscores)
key (too vague)
stripeKey (camelCase instead of SCREAMING_SNAKE_CASE)

Required vs Optional​

Prefix optional variables with:

OPTIONAL_FEATURE_NAME

Or document in .env.example:

# Required
DATABASE_URL=

# Optional - defaults to 10
# DATABASE_POOL_SIZE=

File Naming​

Source Code Files​

  • Use kebab-case for file names
  • Match primary export name (if applicable)
  • Include file purpose in name

Examples:

user-service.ts
auth-middleware.ts
database-connection.ts
api-routes.ts

Configuration Files​

Standard names (don't rename):

.env
.env.local
.env.example
.gitignore
package.json
tsconfig.json
docker-compose.yml

Documentation Files​

  • Use kebab-case
  • Include content type in name
  • Make purpose obvious

Examples:

deployment-guide.md
api-reference.md
user-manual.md
migration-checklist.md

Asset Files​

  • Use kebab-case
  • Include descriptive name
  • Avoid generic names

Good:

logo-horizontal-color.png
hero-image-homepage.jpg
icon-user-avatar.svg

Bad:

image1.jpg
logo.png (if multiple logos)
file.pdf

Slack Channels​

Format​

#category-specific-topic

Rules​

  • Use kebab-case
  • Start with category prefix
  • Be specific about purpose

Categories & Examples​

Projects:

#project-client-name
#project-website-redesign
#project-fpd-dashboard

Teams:

#team-engineering
#team-marketing
#team-operations

Topics:

#topic-deployments
#topic-incidents
#topic-releases

Alerts:

#alerts-production
#alerts-staging
#alerts-monitoring

General:

#general
#random
#announcements
#help

Temporary:

#temp-migration-2024
#temp-launch-week

Channel Naming Guidelines​

  • Avoid creating similar channels (check existing first)
  • Archive inactive channels
  • Use channel description to explain purpose
  • Pin important messages/docs

Database Tables & Collections​

Format​

plural_noun

Rules​

  • Use snake_case
  • Use plural form
  • Be explicit about relationships

Examples​

Good:

users
projects
project_members
user_settings
audit_logs

Bad:

user (singular)
UserSettings (PascalCase)
tbl_users (unnecessary prefix)

Junction Tables​

For many-to-many relationships:

table1_table2

Examples:

users_projects
projects_tags

API Endpoints​

REST API Format​

/resource-name
/resource-name/:id
/resource-name/:id/sub-resource

Rules​

  • Use kebab-case for multi-word resources
  • Use plural nouns for collections
  • Use HTTP verbs (GET, POST, PUT, DELETE)
  • Use nested routes for relationships

Examples​

Good:

GET    /users
GET    /users/:id
POST   /users
PUT    /users/:id
DELETE /users/:id

GET    /users/:id/projects
GET    /project-members
POST   /auth/login
POST   /password-reset

Bad:

/getUsers (verb in URL)
/user/:id (singular)
/users_list (underscore)
/api/v1/users/getUserById (too verbose)

Versioning​

/v1/resource
/v2/resource

Or use headers:

Accept: application/vnd.api+json; version=1

Function & Variable Names​

JavaScript/TypeScript​

  • Functions: camelCase, verb + noun
  • Variables: camelCase, descriptive nouns
  • Constants: SCREAMING_SNAKE_CASE
  • Classes: PascalCase
  • Interfaces/Types: PascalCase with 'I' prefix (optional)

Examples:

// Functions
function getUserById(id: string): User { }
async function fetchProjectData(): Promise<Project> { }

// Variables
const userName = 'John';
let projectCount = 0;
const apiResponse = await fetch(url);

// Constants
const API_BASE_URL = 'https://api.example.com';
const MAX_RETRY_ATTEMPTS = 3;

// Classes
class UserService { }
class DatabaseConnection { }

// Interfaces/Types
interface User { }
type ApiResponse = { }

Python​

  • Functions: snake_case
  • Variables: snake_case
  • Constants: SCREAMING_SNAKE_CASE
  • Classes: PascalCase

Examples:

# Functions
def get_user_by_id(id: str) -> User:
    pass

async def fetch_project_data() -> Project:
    pass

# Variables
user_name = "John"
project_count = 0

# Constants
API_BASE_URL = "https://api.example.com"
MAX_RETRY_ATTEMPTS = 3

# Classes
class UserService:
    pass

Boolean Variables​

Start with is, has, should, or can:

isLoading
hasPermission
shouldValidate
canEdit
isAuthenticated

Function Naming Patterns​

  • get* - Retrieve data (synchronous)
  • fetch* - Retrieve data (asynchronous, often API calls)
  • set* - Set a value
  • update* - Update existing data
  • create* - Create new data
  • delete* - Remove data
  • validate* - Check validity
  • handle* - Event handlers
  • on* - Event listeners

Domain Names & Subdomains​

Format​

[service].[environment].[domain.com]

Examples​

Production:

example.com
www.example.com
api.example.com
app.example.com

Staging:

staging.example.com
api.staging.example.com

Development:

dev.example.com
api.dev.example.com

Services:

docs.example.com
status.example.com
blog.example.com
admin.example.com

Rules​

  • Production services have no environment prefix
  • Non-production includes environment in subdomain
  • Keep subdomain names short and descriptive

Docker & Containers​

Image Names​

service-name:tag

Examples:

company-api:latest
company-api:v1.2.3
company-web:production
company-worker:staging

Container Names​

service-name-environment

Examples:

company-api-production
company-web-staging
company-worker-dev

AWS Resource Names​

Format​

[project]-[environment]-[resource-type]-[description]

Examples​

Good:

company-prod-s3-user-uploads
company-staging-rds-main-db
company-prod-lambda-image-processor
company-prod-ec2-web-server-1

Bad:

bucket1
database
lambda-function

Tags & Labels​

Kubernetes Labels​

app: application-name
environment: production
version: v1.2.3
team: engineering

Git Tags​

v1.0.0
v2.1.0-beta
v1.5.0-rc.1

Follow Semantic Versioning:

  • MAJOR.MINOR.PATCH
  • Increment MAJOR for breaking changes
  • Increment MINOR for new features
  • Increment PATCH for bug fixes

Documentation Files​

System Profiles​

[system-name]-profile.md

Examples:

  • egi-website-profile.md
  • fpd-api-profile.md

SOPs​

[action]-[system/process].md

Examples:

  • deploy-production-website.md
  • backup-database.md
  • rotate-api-keys.md

Runbooks​

[system]-[scenario]-runbook.md

Examples:

  • api-downtime-runbook.md
  • database-failover-runbook.md

Configuration & Secrets​

Secret Names​

COMPONENT_SECRET_TYPE

Examples:

DATABASE_PASSWORD
API_SECRET_KEY
JWT_SIGNING_KEY
STRIPE_SECRET_KEY
OAUTH_CLIENT_SECRET

Config File Names​

config.[environment].json

Examples:

config.production.json
config.staging.json
config.development.json
config.test.json

Enforcing Conventions​

Tools​

  • Linters: ESLint, Pylint, RuboCop
  • Formatters: Prettier, Black
  • Git Hooks: Husky for commit message validation
  • CI/CD: Automated checks in pull requests

Code Review Checklist​

  • Names follow project conventions
  • No single-letter variables (except loop counters)
  • Boolean variables start with is/has/should/can
  • Function names are verb phrases
  • No abbreviations (unless standard)
  • Consistent casing for file type

When to Break the Rules​

These are guidelines, not absolute rules. Break them when:

  1. Following a framework convention (e.g., Next.js uses pages/ directory)
  2. Industry standard differs (e.g., Dockerfile not dockerfile)
  3. Existing codebase uses different convention (be consistent with codebase)
  4. Legacy system requirements (interfacing with old system)

When breaking rules, document why in comments or PR description.

Resources​

Contributing​

To suggest changes to these conventions:

  1. Open a discussion with the team
  2. Provide reasoning and examples
  3. Get consensus before updating
  4. Update all relevant documentation
  5. Announce changes to the team