peteraritchie / namingthings Goto Github PK

Content on tips, tricks, advice, practices for naming things in in software/technology

License: GNU General Public License v3.0

naming programming design class variable concepts advice adjective noun consistency

namingthings's Introduction

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.

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

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

namingthings's People

Contributors

Stargazers

Watchers

Forkers

darwinphi mahdimp alawadi86 mvandermeulen

namingthings's Issues

Possible reference detail

from: https://www.macmillanthesaurus.com/topics/verb-forms-and-tenses

Verb-related Words

aspect (NOUN)

LINGUISTICS the form of a verb group indicating whether an action, event, or situation is seen as continuing or as complete. In English there are two aspects, the progressive, such as ‘is arriving’ or ‘was arriving’, and the perfective, such as ‘has seen’ and ‘had seen’.

auxiliary verb (NOUN)

the verbs ‘be’, ‘do’, and ‘have’ in English, when they are used with another verb to form tenses, questions, question tags, and the passive. For example in the sentences ‘I am listening’, ‘Are you working?’, ‘You don’t like her, do you?’ and ‘The bill has been paid’, ‘am’, ‘are’, ‘do’, and ‘has been’ are all auxiliaries.

conjugation (NOUN)

the way that you conjugate a particular verb

conjugation (NOUN)

a group of verbs that all conjugate using the same pattern

copula (NOUN)

a linking verb

do (VERB)

used instead of repeating the same verb that was used earlier in the sentence, or in a previous sentence

the first person (NOUN)

LINGUISTICS the form of the pronoun or verb that you use about yourself, and about someone who is with you. The first person pronouns in English are ‘I’, ‘me’, ‘we’, and ‘us’.
first/second/## third person (PHRASE)
the forms of pronouns or verbs that show who is being referred to. People ## use the first person (I) to refer to themselves, ## the second person (you) to refer to the person or people they are talking to, and the third person he/she/they to refer to anyone else

the future (NOUN)

LINGUISTICS the forms of a verb group used to talk about time after the present. In English future time is usually indicated using ‘will’ or a form of ‘be’ followed by ‘going to’, and the infinitive of a verb. For example in the sentences ‘Full details of all courses will be available shortly’ and ‘We are going to play brilliantly’, the verb groups ‘will be’ and ‘going to play’ indicate future time.

the future perfect (NOUN)

the tense used to talk about actions or states that will be finished or in progress at a particular time in the future. The future perfect consists of ‘will have’ and a past participle, for example ‘will have risen’ in the sentence ‘It’s likely that by 2100, average world temperatures will have risen by two to five degrees’.

the historic present (NOUN)

the use of present tenses to refer to past time, especially when you want to make a narrative sound more exciting. For example, in sentence ‘The next day he sees the girl again, but this time he asks her if she’d like to go to the fairground’, the verbs ‘see’ and ‘ask’ ## are in the historic present (present simple).

imperative (NOUN)

LINGUISTICS the form of a verb that expresses orders. The imperative is also called the imperative mood.

indicative (NOUN)

a form of a verb used for making statements or asking questions

infinitive (NOUN)

the basic form of a verb. In English, this form of the verb together with the word ‘to’ in front of it is usually called a to-infinitive, and the verb form on its own is usually called a bare infinitive.
##- ing form (NOUN)
a word that is formed by adding -ing to the base form of a verb, for example ‘walking’ from ‘walk’, or ‘stopping’ from ‘stop’

irregular verb (NOUN)

a verb that does not follow the usual rules of grammar. For example, ‘eat’ is an irregular verb because its past tense is ‘ate’ and its past participle is ‘eaten’, not ‘eated’.

lexical verb (NOUN)

a verb that has lexical meaning rather than serving a grammatical function. ‘Live’, ‘laugh’ and ‘love’ are all lexical verbs.

linking verb (NOUN)

a verb such as ‘be’, ‘seem’, and ‘appear’ that connects the subject of a clause with a complement. For example in the sentence ‘He was a cheerful man and seemed happy in his old age’, ‘was’ and ‘seemed’ are linking verbs, and ‘a cheerful man’ and ‘happy’ are its complements.

modality (NOUN)

LINGUISTICS the ways in which people talk about their attitudes, obligations, and intentions. In English, modality is expressed by modal verbs such as ‘can’, ‘might’, and ‘should’, or by expressions such as ‘It’s likely that’, ‘I’m supposed to’, and ‘I’d better’.

modal verb (NOUN)

a verb such as ‘must’, ‘may, ‘could, or ‘would’, that is used with another verb to express ideas such as obligation, permission, possibility, and intention. For example in the sentences ‘I can imagine what he would say to that’ and ‘Appointments should be made a week in advance’, ‘can’, ‘would’, and ‘should’ are modal verbs.

mood (NOUN)

LINGUISTICS a group of verb forms that are used to show whether, for example, a sentence is a statement, question, or order

participle (NOUN)

in English, ## the present participle (‘-ing’ form) ## and the past participle (‘-ed’ form) of a verb, that are used for forming different tenses, in non-finite clauses, in passives, and as modifiers. For example in the sentences ‘Are you listening?’, ‘After graduating she worked as a bus driver’, ‘Lunch is served at noon’, and ‘He begins the season with an injured foot’ the words ‘listening’, ‘graduating’, served’, and ‘injured’ are all participles.

the past (NOUN)

LINGUISTICS the forms of a verb group indicating that an action or event happened regularly, or that a situation existed or was true during a period before now. For example ‘he worked’, and ‘she was working’ are both in the past.

the past continuous (NOUN)

the tense used to talk about actions or behaviour that were begun and ended at some time in the past. The past continuous consists of ‘was’ or ‘were’ and a present participle. For example, in the sentences ‘She was shaking with cold’ and ‘Were they telling the truth?’, the verb groups ‘was shaking’ and ‘were telling’ are past continuous.

past participle (NOUN)

in English, the ‘-ed’ form of a verb, that is used for forming the perfect tenses, in the passive, and as a modifier. For example, in the clauses ‘Have you eaten yet’, ‘Payment must be made immediately’, and ‘Do you like fried fish?’, the words ‘eaten’, ‘made’ and ‘fried’ are all past participles.

the past perfect (NOUN)

the past perfect simple and the past perfect continuous are the tenses used to talk about actions, behaviour, or situations that began at a particular time in the past and were either complete or still continuing at that time. The past perfect simple consists of ‘had’ and a past participle, for example the verb group ‘had reached’ in the sentence ‘By 1901 the population of London had reached over six-and-a-half million’. The past perfect continuous consists of a form of ‘had’ followed by ‘been’ and a past participle, for example ‘had been planning’ in the sentence ‘By February, he had been planning the event for seven months’.

the past simple (NOUN)

the tense used to talk about habitual actions, behaviour, or situations that happened or existed before now. The simple past of regular verbs consists of the infinitive with ‘-d’ or ‘-ed’ added, for example ‘arrived’ in the sentence ‘She arrived yesterday’. The auxiliary ‘did’ is used in questions and negatives, for example in the sentences ‘Did you see that?’ and ‘Sometimes his plans did not succeed’.

perfective (ADJECTIVE)

the perfective aspect indicates that an action, situation, or event is seen as complete at a particular time. The perfective verb group consists of a form of ‘have’ and a past participle. For example, in the sentence ‘The voters have decided it’s time for a change’, ‘have decided’ refers to a point in time before now. In the sentence ‘After we had finished all the food, more people arrived’, ‘had finished’ refers to a point in time before ‘more people arrived’.

phrasal verb (NOUN)

a combination of a verb and an adverb or preposition, which has a particular meaning, such as ‘look after’, ‘hurry up’, ‘give in’, ‘chill out’, ‘get away with’ and ‘bring up’. For example in the sentence ‘Don’t tell me how to bring up my children!’, ‘bring up’ means ‘raise’. An adverb or preposition in a phrasal verb is sometimes called a particle.

the pluperfect (NOUN)

the past perfect tense of a verb

the present (NOUN)

LINGUISTICS the forms of a verb group indicating that an action or event happens regularly or is taking place now, or that a situation exists or is true now. For example ‘she works’ and ‘she’s working’ are both in the present.

the present continuous (NOUN)

the tense used to talk about actions or behaviour that are in progress now or planned for the future. The present continuous consists of ‘am’, ‘is’ or ‘are’ and a present participle. For example, in the sentences ‘What is she trying to achieve?’, ‘We are listening carefully to all your suggestions’, and ‘I’m leaving for China tomorrow’, the verb groups ‘is trying’, ‘are listening’ and ‘am leaving’ are present continuous.

present participle (NOUN)

in English, the ‘-ing’ form of a verb, that is used for forming the ‘continuous’ present and past, and as a noun or noun modifier. For example in the sentence ‘They were behaving in a threatening manner’, ‘behaving’ and ‘threatening’ are present participles.

the present perfect (NOUN)

the present perfect simple and the present perfect continuous are the tenses used to talk about actions, behaviour, or situations that began in the past and are complete or still continuing at the present moment. The present perfect simple consists of a form of ‘have’ and a past participle, for example the verb group ‘have bought’ in the sentence ‘I’ve bought the tent so let’s go camping!’ The present perfect continuous consists of a form of ‘have’ followed by ‘been’ and a present participle, for example ‘has been living’ in the sentence ‘My niece has been living with us all her life’.

reciprocal verb (NOUN)

a verb that describes something that two people do to or with each other, for example the verb ‘meet’ in the sentence ‘We always meet in the park’.

reflexive verb (NOUN)

a verb whose subject and object refer to the same person or thing. The object is a reflexive pronoun. For example, in the sentence ‘I thoroughly enjoyed myself while I was there’, ‘enjoy’ is a reflexive verb and ‘myself’ is a reflexive pronoun.

reporting verb (NOUN)

a verb such as ‘say’, ‘warn’ or ‘explain’ that is used to report what someone has said

the second person (NOUN)

the pronoun or form of a verb that refers to the person you are talking to. In English the second person pronoun is ‘you’.

split infinitive (NOUN)

an infinitive in which there is an adverb between the word ‘to’ and the verb, as in the phrase ‘to completely understand’. Some people avoid this because they think it is bad style or incorrect.

subjunctive (NOUN)

the form of a verb that is used for expressing doubts and wishes. For example, in the sentence ‘I wish I were taller’, ‘were’ is in the subjunctive. The indicative is used for making statements and asking questions about facts, and the imperative is used for telling someone to do something.

tense (NOUN)

the forms of a verb group indicating whether an action, event, or situation happens or exists now, before now, or in the future. In English, the verb has present and past tense forms such as ‘arrive’ and ‘arrived’. Other verb groups indicating tense or time include participles and auxiliary verbs, for example ‘are arriving’, ‘have arrived’, ‘had arrived’, and ‘will arrive’.

the third person (NOUN)

the set of pronouns and verb forms used for referring to someone or something that is not the speaker or the person being spoken to

v (ABBREVIATION)

LINGUISTICS verb

verb (NOUN)

a word such as ‘remain’, ‘run’, or ‘find out’ that refers to an action, event or state

verbal (ADJECTIVE)

LINGUISTICS acting as a verb, or relating to a verb

verbally (ADVERB)

LINGUISTICS using a verb

verb group (NOUN)

a group containing at least one verb (the head), and often other words such as auxiliaries and modal verbs. For example, ‘could be’, ‘shouted’, ‘must go’, and ‘have been robbed’ are all verb groups.

verbing (NOUN)

an example of a verb that has come from a noun, for example ‘impact’ in the sentence ‘How will this impact our sales going forward?’

voice (NOUN)

LINGUISTICS in English, voice refers to the choice of either an active verb group or a passive verb group. In the active voice, the subject is the person or thing that does or is responsible for the action of the verb. In the passive voice, the subject is the person or thing that is affected by the action of the verb. For example in the sentence ‘The kids have learnt the importance of a healthier diet’, the verb group ‘have learnt’ is active. In the sentence ‘Lessons will be learnt from this disaster’, the verb group ‘will be learnt’ is passive.

Possible additional advice

from: https://ux.stackexchange.com/a/43188

You can argue that people will agree on these definitions:

You create something from scratch. Like create a new report.
Once in existence, you add something to a container. Like adding a person to the managers group.
By modifying something you change its properties. Like modifying a design.
By updating something you change the data, but not the design. Like updating someone's phone number.
By changing something you replace one existing thing with another. Like changing your profile photo.
By removing something you take it out of a container. Like removing something from the fridge - the thing still exist.
By destroying something you do the opposite from creating - gone forever. Like destroying a toy.
By deleting something you wipe if off, so it is no longer retrievable. This is said with the obvious exception that nowadays people are accustomed to the 'undelete' feature. So somewhat of an ambiguity here, but it is a standard in interfaces to use the term for permanent delation.

#My Recommendations

Prefer Add over Create unless there's a clear create-then-add mechanism. Although technically (and as you said) create means it never existed before, while programmers think about 'records' users think about metaphors. While for you adding a person's record makes perfect sense, 'creating a person' or 'creating a task' is less intuitive than 'adding a person' (to the system) or 'adding a task' (to the task list). Obviously, if your users are IT professionals and fluent with what a database and records are, prefer create over add.
If persistance is involved, prefer update over change. Having said that, users are accustomed to 'save changes'. Don't use modify.
Prefer Remove for non-permanent removal, and Delete for permanent removal.

Attribution: https://ux.stackexchange.com/a/43188