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 really 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 important.

Scope

These guidelines focus on wording over 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, bread 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, that 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 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 necessarily
    pronounced the same and having different meanings and origins.
    Homonym is a type of homograph.

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 functionality of implemented by those types.

Use a pluralized noun 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 as collections.

Use a mass deverbal noun 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 responsibility. Avoid ending in "-ion", avoid words ending in "-tion" or "-sion. A "mass moun" 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 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 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 it's 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

General

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 different meaning.
Metonym means a word substituted for another with a different meaning.

Idiosyncratic Guidelines

There get more into what you might call "non-generic" identifier guidelines, guidelines that complement the from-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 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 a 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 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 participles 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 the meanings described here:

• Created signifies something new as come into existence (rather than Added).
• Added signifies something as 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 progres **

References

.NET Framework Guidelines - Naming