Naming Conventions

This guide documents our established naming patterns across the codebase, with examples from our actual implementation.

Component Names

File Names

components/
  newsletterForm/           # camelCase for directories
    newsletterForm.tsx      # camelCase.tsx for component files
    newsletterForm.test.ts  # camelCase.test.ts for test files
    index.ts                  # index.ts for exports

🤔 Why This Pattern?

• Consistent file organization
• Clear component boundaries
• Easy imports
• Testability focus

Component Functions

// ✅ Do: PascalCase for component functions
export function NewsletterForm(props: NewsletterFormProps) {
  // ...
}

// ✅ Do: PascalCase for compound components
NewsletterForm.Header = function NewsletterHeader() {
  // ...
};

// ❌ Don't: camelCase for component functions
export function newsletterForm() {
  // wrong
  // ...
}

State Management

Signal Names

// ✅ Do: Descriptive pairs with clear intent
const [isLoading, setIsLoading] = createSignal(false);
const [activeTab, setActiveTab] = createSignal("overview");
const [hasError, setHasError] = createSignal(false);

// ❌ Don't: Unclear or abbreviated names
const [l, setL] = createSignal(false); // wrong
const [tab, setTab] = createSignal("overview"); // too vague
const [error, setError] = createSignal(false); // prefer isError for booleans

Event Handlers

// ✅ Do: handle[Event] pattern
const handleSubmit = (e: Event) => {
  // ...
};

const handleTagClick = (tag: string) => {
  // ...
};

// ❌ Don't: Inconsistent patterns
const submit = (e: Event) => {
  // wrong
  // ...
};

const clickTag = (tag: string) => {
  // wrong
  // ...
};

GraphQL Operations

Query Files

pages/articles/[slug]/
  _graphql/
    page.query.graphql      # Main query
    validate.query.graphql  # Validation query
    api.ts                  # API functions
    transform.ts           # Data transformations

Function Names

// ✅ Do: Descriptive action-based names
export async function getArticleBySlug(slug: string) {
  // ...
}

export async function validateArticlePageAPI(slug: string) {
  // ...
}

// ❌ Don't: Vague or inconsistent names
export async function article(slug: string) {
  // wrong
  // ...
}

export async function checkArticle(slug: string) {
  // wrong
  // ...
}

Utility Functions

Transform Functions

// ✅ Do: Clear transformation intent
function formatReadingTime(minutes: number): string {
  return `${minutes} min read`;
}

function transformArticleData(raw: RawArticle): Article {
  // ...
}

// ❌ Don't: Ambiguous names
function format(minutes: number): string {
  // wrong
  // ...
}

function articleTransform(raw: RawArticle): Article {
  // wrong
  // ...
}

Helper Functions

// ✅ Do: Action-based names for helpers
function validateEmail(email: string): boolean {
  // ...
}

function sanitizeHtml(content: string): string {
  // ...
}

// ❌ Don't: Unclear purpose
function checkInput(value: string): boolean {
  // wrong
  // ...
}

function clean(content: string): string {
  // wrong
  // ...
}

Constants and Types

Constants

// ✅ Do: UPPER_SNAKE_CASE for constants
export const MAX_ITEMS_PER_PAGE = 20;
export const DEFAULT_LOCALE = "en-US";

// ❌ Don't: Inconsistent casing
export const maxItemsPerPage = 20; // wrong
export const DefaultLocale = "en-US"; // wrong

Types and Interfaces

// ✅ Do: PascalCase for types/interfaces
export interface ArticleProps {
  title: string;
  content: string;
}

export type LoadingState = "idle" | "loading" | "error" | "success";

// ❌ Don't: Non-PascalCase
export interface articleProps {
  // wrong
  // ...
}

export type loadingState = "idle" | "loading"; // wrong

Best Practices

1. Consistency

   • Follow established patterns
   • Use consistent casing
   • Match file names to exports
   • Group related names

2. Clarity

   • Use descriptive names
   • Avoid abbreviations
   • Indicate boolean nature
   • Show clear intent

3. Organization

   • Group related files
   • Use consistent directory structure
   • Follow component boundaries
   • Maintain test naming

4. Documentation

   • Document unusual names
   • Explain abbreviations
   • Note naming patterns
   • Keep README updated

Decision Checklist

When naming new code elements, ask:

1. Component Names

   • Is it PascalCase?
   • Does it match the file name?
   • Is it descriptive?
   • Does it follow team patterns?

2. Function Names

   • Does it describe the action?
   • Is it consistently cased?
   • Is it clear and specific?
   • Does it match similar functions?

3. File Structure

   • Does it follow directory patterns?
   • Are test files named correctly?
   • Are GraphQL files organized?
   • Is the index.ts present?

4. State and Props

   • Are signal pairs clear?
   • Do boolean names indicate state?
   • Are prop names consistent?
   • Are types properly cased?