01-17-23 UPDATE: Added THAT 2023 Slides
01-12-23 UPDATE: Added CodeMash 2023 Slides
10-3-22 UPDATE: Added Prairie Dev Con 2022 Regina Slides
8-8-22 UPDATE: Added KCDC 2022 Slides
3-11-21 UPDATE: Added example of organizational guidance
10-17-19 UPDATE: Techcon '19 version of the slides are now available

Naming Things

Content (TL;DR) on tips, tricks, advice, practices for naming things in software/technology

Drivers

Naming guidance like .NET Framework Guidelines are helpful, but they only help in minor situations and don't do a lot to help solve the naming things problem in software.

Vision

Detail research results around where some of the pain points in naming are, analyze potential solutions and provide guidance for making naming things easier.

Guiding Principles

• There are always exceptions; we can only mitigate their effect
• Purposefulness This means doing this "on purpose", or by design.
• Consistency Enough said
• Least Astonishment Building on consistency, where consistency of intuitiveness is essential.

Scope

These guidelines focus on wording and less on capitalization. "Casing" is important, but that is a separate, independent style.

Detailed Guidance

Definitions

countable noun

/ˈkoun(t)əb(ə)l/
adjective
    a noun that can form a plural or be used with the indefinite article.

Antonyms: uncountable noun

mass noun

/ˈmas ˌnoun/
noun
    a noun that is usually uncountable but can be made plural or used with a or an when you are talking about different types of something.
    For example, "breads" is used as a mass noun in the shop sells several different breads.

uncountable noun

/ˌənˈkoun(t)əb(ə)l noun/
adjective
    a noun that cannot form a plural or be used with the indefinite article.

collective noun

/kəˈlektiv noun/
noun
    a singular noun, such as "committee" or "team" refers to a group of people, animals, or things. [In American English it must be used with a singular verb]

deverbal

/ˌdēˈvərb(ə)l/

adjective
    (of a noun or adjective) derived from a verb but behaves strictly as a noun or adjective and not a verb.

noun
   a deverbal noun or adjective.

See also: verbal noun

action noun

/ˈakSH(ə)n noun/
noun
    A noun expressing action.

synonyms:
    noun of action

verbal noun

/ˈvərbəl noun/
noun
    A that is noun formed as an inflection of a verb and partly sharing its constructions[/forms. i.e., sometimes behave as a verb].

"Verbal nouns contrast with deverbal nouns, that is, other kinds of nouns derived from verbs, such as attempt, destruction, and including nouns ending in -ing that do not have verbal force: building in The building was empty. They also contrast with the gerund, which also ends in -ing, but is syntactically a verb."

See also: deverbal

zero-derivation words

noun
    A process of word-formation in which there is no change to the form that undergoes it.
    e.g., that by which the verb fish, seen as one lexical unit, is derived from the noun fish, seen as another lexical unit.

Synonyms: zero-affixation words.

metonym

/ˈmedəˌnim/ noun     a word, name, or expression used as a substitute for something else with which it is closely associated.
    For example, Washington is a metonym for the federal government of the US.

homograph

/ˈhäməˌnim,ˈhōməˌnim/ noun     each of two or more words spelled the same (homonym) but not
    pronounced the same and have different meanings and origins.
    Homonym is a type of homograph.

Prefer English Language Grammar Conventions

Ordering of Adjectives in Noun Phrases

English grammar order adjectives by relation, in the following order preceding the noun: 1) opinion, 2) size, 3) physical quality, 4) shape, 5) age, 6) color, 7) origin, 8) material, 9) type, 10) purpose. Examples:

• strange, green, metallic material (1, 6, 8)
• long, narrow, plastic brush (2, 4, 8)
• round, Italian, bread-like Christmas cake (4, 7, 9)
• beautiful, tall, thin, young, black-haired, Scottish person (1, 2, 3, 4, 5, 6, 7)
• amazing, little, old, Chinese cup and saucer (1, 2, 5, 7)

Principles

Compartmentalization Compartmentalize things that can be reasoned about independently of other things; these are the things that require unique names. One thing that makes naming hard is naming things that have no unique attributes or behavior.

Namespaces

Namespaces suit a couple of needs, both relating to the grouping of types. Grouping types within a namespace should be based on the functionality implemented by those types.

Use a pluralized noun or noun phrase for namespaces that group types related by interface A namespace that contains types related by interface should be named with a pluralized noun. One is a grouping of types that implement a specific interface. A Collections suffix signifies the namespace contains types that implement interfaces that allow types to act like collections.

Use a mass deverbal noun or noun phrase for namespaces that group types related by functionality (but different). The other grouping can cause some consternation because the grouping can easily feel subjective. You can also group types by functional usage. This type of grouping can be thought of as capability grouping. In which case, the namespace name can be a noun of action or a noun based on a verb. The suffixes "-ion" and "-ing" come into play here. e.g., Processing or Administration.

Use countable nouns or pluralized adjectives for namespaces that classify other namespaces System.Diagnostics.Tracing

Use adjectives or mass nouns to sub-group types related by interface System.Collections.Generic, System.ComponentModel.Composition.

Being successful: Perform grouping on purpose, only group types with similar attributes or similar behavior (randomly grouping types within a namespace is very subjective, and thus a good name for it is subjective). Prefer nouns that describe an act or a responsibility. Avoid ending in "-ion", avoid words ending in "-tion" or "-sion. A "mass noun" is also called a noncountable noun. Avoid words that function as mass deverbal nouns but often also function as adjectives (need example).

Summary

Namespace names should signify how the types in the namespaces are grouped.

See also General

Assemblies; Class Libraries and Programs

Assemblies are the deployable binary groupings of compiled code. As such, the context of these binaries is generally the file system or URIs. Assemblies often travel in packages and thus have unique constraints that affect naming. Assembly names can be scoped by directory, but that depends on deployment and choices outside of your control (names of 3^rd party assemblies and packages).

Classes

Prefer Common nouns A common noun is a noun that isn't a proper noun: they are names for general things rather than names that identify specific things.

Being Successful Avoid plural, mass, and collective nouns; as well as words that act as nouns and other parts of speech.

See also General

Value Types

Avoid deverbal nouns or noun phrases for value types (nouns derived from verbs, e.g., words suffixed with -or, -ant, -ar -ian, -er, etc.)

See also General

Structs

Structs often function as value types; avoid deverbal nouns or noun phrases for structs (nouns derived from verbs, e.g., words suffixed with -or, -ant, -ian, -er, etc.)

See also General

Interfaces

Prefer Adjectives Formed From Verbs Adjectives describe attributes of something, like abilities. Not all adjectives describe abilities, but as an interface is a representation of an ability, the name should represent an action (formed from a verb).

The suffixes -able, -ible, and -ive are important: these suffixes form adjectives from verbs (actions, abilities). -able/-ible are used with verbs for interfaces representing an inherent ability of an implementation (Enumerable in IEnumerable, to represents something that you can enumerate) (or something that has the ability to be enumerated). -ive is used with verbs for interfaces that perform a type of functionality (Transmissive in ITransmissive for something that transmits).

-able/-ible something that can have an action performed on it.
-ive something that performs an action.

See also General

Variables

Members

See also General

Parameters

See also General

Branches

• bugfix/description
• features/feature-name
• features/feature-area/feature-name
• hotfix/description
• users/username/description
• users/username/workitem

See also

General

Avoid Ending in a Prepositional Phrase
There's a myth that ending a sentence in a preposition is bad form. This is a stalwart of Latin accepted practices. But, avoiding dangling (hanging, stranded) prepositions is generally preferred (which may be where the ending-in-a-preposition comes from because it usually results in a dangling preposition). Most of the advice here is to use a noun/adjective or a noun/adjective phrase as an identifier names. This means a name ending with a preposition doesn't follow this advice. I also advise against ending an identifier name with a prepositional phrase. e.g., IsResidentOfCommunityPropertyState," Resident of a community property state is a noun phrase but it actually consists of a noun ("Resident") and prepositional phrase ("a community property state"). The example can be reworded to IsCommunityPropertyStateResident so that the ends in a noun (and follows as verb/noun form, or more specifically past-participle/subject form for boolean identifiers.)

Avoid Ambiguity
Avoid using words that are prone to misinterpretation or are used to mean many things.

Avoid Zero Derivation Words (Avoid Homographs or Avoid Metonyms ("e.g., 'Washington' to mean 'federal government' Also: nounification, e.g.: 'ask' in place of 'question'. ")) Zero derivation words are when a new "word" (meaning) is created from another word without using derivation (e.g., affixes are common in creating new meanings and words, deriving them from a root word and adding the affix).

Homograph is another name for words spelled the same, but with a different meaning.
Metonym means a word substituted for another with a different meaning.

Idiosyncratic Guidelines

These get more into what you might call "non-generic" identifier guidelines, guidelines that complement the form-of-speech rules.

Messages - Events

An event is the embodiment of a significant change in state. (Event-driven architecture n.d.) That fact (the occurrence) is recognized by the software and represented by an instance of an event identifier. It is a fact about something that happened in the past, it cannot be changed nor retracted. (Bonér 2017) A domain event signals something that has happened in the outside world that is of interest to the application. It's transmitted to the application in some data structure (event identifier), carrying with it the data that describes the event. (Fowler 2006)

Prefer to name event identifiers with a <subject><verb> convention. Subject is a common noun or a noun phrase and the verb should have tense in the past (past participle). Not all past participles take this form, but typically past participles are a simple present tense verb suffixed with "-ed".

Prefer the subject name to be the name of the domain resource whose state changed. Resources should be domain-specific and should not relate to implementation detail; avoid "record", "field", etc.

To Avoid Ambiguity Prefer to limit the number of past participles used. Also, prefer to choose a single past participle for a particular circumstance. Without getting lost in philosophy, here's a list of past participles for use with common event/state-change scenarios in software:

Generic Outcome-based Event Name Suffixes

This is a fairly complete list of generic types of events; when used, they should be consistent with the meanings described here:

• Created signifies something new has come into existence (rather than Added).
• Added signifies something has been added to a container or collection.
• Updated signifies the value properties or attributes of an existing thing (entity) have been changed.
• Changed signifies an entire thing (entity) has been replaced with another.
• Deleted means something is no longer accessible in some context.
• Destroyed means removed from existence, no possible way to ever get it back.
• Removed means the opposite of Added, a thing has been moved out of or removed from a container/collection
• Modified means structure or schema has changed and isn't related to instantiated entities.

There will, of course, be domain-specific past tense verbs. For example, Qualified, Eligible. Be faithful to the domain; if Qualified is an important event, model it in addition to the resource being updated: ClientQualified, ClientUpdated.

Examples of Domain-specific Past Participles for Event Naming

• Locked As in Interest Rate _Locked.
• Moved As Client Moved to a different address.
• Sent As in Underwriting Request Sent.
• Corrected As in Client Name Corrected.
• Began As in Loan Processing Began.
• Completed As in Underwriting Completed.
• Rejected As in Application Rejected.

Messages - Commands

** in progress **

Organizational Guidelines

What is described here is designed around grammar and thus very systematic and repeatable (automatable, someday.) That's doesn't mean it's perfect for everyone. As with languages, there are dialects. Each person or organization may have its own dialect, eh. So I highly recommend documenting that dialect. That could be to reference this and show additions. Copy this and modify it. etc...

Example Organizational Guidance

Naming Suffixes

• Date & Time : …DateTime
• Date: …Date
• Counts: …Count
• Identifiers: …Identifier
• Text: …Name, …Description, …DisplayText
• Percentages: …Ratio
• Interest Rates: …Rate, with a precision of three decimal places; unique from Ratio
• Monetary Values: …Amount, …Payment

Naming Prefixes

Assertions

• Attribute (property) assertions have a prefix that is a present/past/third-person of the verb to be
        “Is,” “Are,” “Was,” “Were,” “Has,” or “Had.”
• Behavior (act, action) assertions have a prefix that is a future-tense form of the verb able to
        “Is,” “Are,” “Was,” “Were,” “Has,” or “Had,” or “Can.”

References

.NET Framework Guidelines - Naming
The importance of naming in programming - Carl Alexander
A Guide for Naming Things in Programming
Adjectives: order - English Grammar Today - Cambridge Dictionary
changelog.com change type naming
Azure Resource Tagging Practices