{ random memes }

Semantic-sort naming

Have adopted a set of conventions for naming that so far lacked a name. :)

My personal timeline dates back before the introduction of CamelCase naming. CamelCase was cool in 1984 as Macintosh was cool. Java and C++ adopted in the 1990s what was then cool. For the folk that came along later, CamelCase was gospel.

A couple decades back, I become dissatisfied with the usual CamelCase conventions. Adopted what I might describe as "structured" naming conventions, but was not satisfied with the label.

Of late was playing with LLMs. As part of describing a project skeleton for working with LLMs, had to capture my naming conventions. Described my naming conventions, and the LLM suggested those names had a semantic sort. Found this an excellent suggestion, so now I have a label. :)

Came up with a definition of semantic-sort naming:

With below as the current version.


Semantic-Sort Naming

A semantic-sort name uses stable components in this order:

<domain>_<role>_<purpose>_<variant>

  • Components are ordered from broad meaning to narrow meaning.
  • Components are separated by underscores for identifiers.
  • Missing components are omitted.
  • Names must use the established vocabulary for the project.
  • Acronyms use the established project spelling.
  • If no project spelling exists, use uppercase only when the target language or external API convention requires it.
  • Plural names describe collections or multiple values.
  • Singular names describe one entity, value, or operation target.
  • Boolean names use an established predicate prefix such as is, has, can, or should when the target language permits it.
  • Constants use the target language's conventional constant style.
  • Public API names follow the naming required by the target language, framework, or external API.
  • External names that cannot be changed are preserved.
  • Names required by a language or framework are preserved when changing them would harm correctness or interoperability.

Directory Naming

  • Use stable, semantic-sort directory names.

Filename Structure

  • Use semantic-sort filenames.
  • Related files must share a structured prefix.
  • Feature files use the exact pattern <feature-number>-<feature-name>.md.
  • Avoid CamelCase in filenames unless required by an external convention.
  • Use hyphens or underscores for readability.
  • Do not invent naming schemes.

Identifier Naming

  • Use semantic-sort identifiers composed of ordered semantic components.
  • Use the order:

<domain>_<role>_<purpose>_<variant>

  • Order components from broad meaning to narrow meaning.
  • Use the established project vocabulary.
  • Use descriptive names for identifiers with broad scope.
  • Short identifiers such as i, s, n, p, and o are permitted only in very small scopes.
  • Use o1, o2, and o3 for ordered transformations only when the target language and scope make the sequence clear.
  • Preserve external names that cannot be changed.
  • Preserve names required by a language, framework, or public API.
  • Use the target language's conventional styles for constants, booleans, classes, and public APIs when those styles are required for correctness or interoperability.

Plan Block Naming

  • A plan block uses semantic-sort naming where applicable.

Log Filename Rules

  • Log filenames must begin with the sortable prefix:
    • YYYY-MM-DD-HH-MM-SS-<description>.log.

Script Filename Rules

  • When shell scripts have a likely order in which they might be invoked, use filenames of the form:
    • <number>-<name>.sh

Ordered Prompt Filename rules

  • When prompt files have an order in which applied, use filenames of the form:
    • <number>-<name>.md