Better Field Naming Through Suffixes

In software development, we often spend more time reading code than writing it. A common friction point in a codebase is field names that lie to you—or at least, don't tell the whole truth.

To build more intuitive APIs, data models and database schemas, consider adopting a suffix-based naming convention that prioritizes linguistic flow and data accuracy.

Illustration of a file cabinet organizing data

The "On" Suffix for Time

A common pitfall is naming a field creationDate only to later store a full ISO timestamp (e.g., 2026-01-01T12:40:50Z). This creates a type-mismatch in the developer's mind.

By using the "On" suffix, you create a natural bridge between the event and the time it occurred. It reads better and remains agnostic about whether the precision is a simple date or a high-resolution timestamp.

Avoid: creationDate, updateTimestamp
Prefer: createdOn, modifiedOn

Location and People: "At" vs. "By"

This logic extends beautifully to other data types, helping to standardize how we reference locations and actors.

Use "At" for Places: When referencing a physical or logical location, storedAt or deliveredAt provides immediate clarity without specifying exactly what location data is required. You can include a full address object under the "At" field or you might decide to only include an ID of the address. Additionally, avoiding the word "address" in the field name prevents confusing duplication if you later include addressLine as part of the object.

The Nuance of "By": While createdBy or modifiedBy is common, you should use the "By" suffix with caution. Suffixes like "By" often imply a completed action (e.g., paidBy), which might be misleading if the object is still in a "pending" state.

Role-Based Naming

For people and organizations, it is often superior to name the field after the role the entity plays rather than the action they performed. This keeps the data model descriptive and state-neutral.

Style	Field Name	Why it works
Action-Based	`paidBy: "Bob"`	Assumes the payment is finished.
Role-Based	`payer: "Bob"`	Clear, concise, and accurate regardless of payment status.

Why It Matters

Consistent naming conventions like these reduce cognitive load. When a developer sees "On", they expect some form of a date and/or time. When they see "At", they expect a location. By aligning our field names with natural language, we make our systems self-documenting and much more pleasant to maintain.