naming-things

Naming Things

A humble effort to solve computer science's second-hardest problem.

This repository is packaged as a Claude Code plugin, exposing a naming-things skill that loads these guidelines automatically whenever you write or review code in Claude Code. Install it from the plugin marketplace (the marketplace entry points to this repo).

[!TIP] Alternative usage (no plugin): Simply copy the following snippet into your AGENTS.md or CONTRIBUTING.md file.

When writing code, you MUST ALWAYS follow the [naming-things](https://raw.githubusercontent.com/codingjoe/naming-things/refs/heads/main/README.md) guidelines.
<!--
Bots/Agents MUST use:
curl -sSL https://raw.githubusercontent.com/codingjoe/naming-things/refs/heads/main/README.md | head -n 500
-->

• Classes and Functions
• Unit Tests
• Time
• Abbreviations
• Metrics, Measurements, and Units
• Utils & Helpers
• Synonyms
• Avoid Negations
• Versioning

Preamble

There are only two hard things in Computer Science: cache invalidation and naming things.

— Phil Karlton

This document concerns natural language conventions, not syntax or code style. Rules are language-agnostic, but examples are given in Python.

Classes and Functions

Classes

Class names are nouns or noun phrases. Think German compound nouns. E.g., UserProfile, OrderItem, PaymentProcessor.

Class names are singular because while its instances may represent multiple entities (e.g., a User class representing multiple user instances), the class itself is a blueprint for a single entity.

Inheritance

Specialize, don't generalize. If you feel the urge to name a base class BaseSomething or AbstractSomething, go the other way. Make children more specific, not parents more general.

Do's

class Vehicle:
    """A means of transporting people or goods."""


class Car(Vehicle):
    """A road vehicle, typically with four wheels, powered by an internal combustion engine or electric motor."""


class SUV(Car):
    """A pedestrian death machine."""

Don'ts

class BaseCar:
    """A road vehicle, typically with four wheels, powered by an internal combustion engine or electric motor."""


class SportsCar(BaseCar):
    """Only fun in Germany."""

Functions

Function represents an action a caller can perform. Use verbs or verb phrases. E.g., send(), calculate_total().

Function names must clearly communicate their external behavior, including side effects. E.g., fetch_or_404() makes it explicit that it may raise a 404 error. They must not expose internal implementation details. E.g., avoid send_via_smtp(); use send() instead.

Loose functions should be the exception, not the rule. Prefer class methods or instance methods to group related functionality. If a function includes a noun in its name, it probably belongs to that noun's class. E.g., instead of fetch_user_profile(user_id), implement UserProfile.fetch(user_id).

Methods

Avoid including object names, as the method is probably attached to the wrong class. E.g., instead of user.send_email(), use UserEmail(user).send().

Variables

Avoid assigning variables that are only used once. If a value is asserted immediately or returned in the next line without further access, use it inline.

Unit Tests

Unit tests should match their API counterparts to be easily navigable and discoverable. A simple text search for a function or class must reveal both its implementation and tests quickly.

Test names use double underscores to separate the function or class name from the scenario (e.g., test_get_user__ok, test_get_user__raise_value_error). Test classes are prefixed with Test in Python or wrapped in describe blocks in JavaScript. Test descriptions must use imperative mood and avoid redundant words like "should", "expect", or "it". Assertion messages must add meaningful context beyond the assertion itself or be omitted. In Node.js, use strict assertions by default with import assert from "node:assert/strict" for shorter function names and stricter equality checks.

Do's

def get_user(user_id):
    """Fetch user from database."""
    ...