Promote Clear Usage
- Include all the words needed to avoid ambiguity for a person reading code where the name is used.
- Omit needless words. Every word in a name should convey salient information at the use site.
- Name variables, parameters, and associated types according to their roles, rather than their type constraints.
- Compensate for weak type information to clarify a parameter’s role.
Strive for Fluent Usage
- Prefer method and function names that make use sites form grammatical English phrases.
- Begin names of factory methods with “make”, e.g.
- Name functions and methods according to their side-effects
- Uses of Boolean methods and properties should read as assertions about the receiver when the use is nonmutating, e.g.
- Protocols that describe a capability should be named using the suffixes able, ible, or ing (e.g.
- The names of other types, properties, variables, and constants should read as nouns.
Use Terminology Well
- Avoid obscure terms if a more common word conveys meaning just as well.
- Stick to the established meaning if you do use a term of art.
- Avoid abbreviations. Abbreviations, especially non-standard ones, are effectively terms-of-art, because understanding depends on correctly translating them into their non-abbreviated forms.
- Embrace precedent. Don’t optimize terms for the total beginner at the expense of conformance to existing culture.
- Document the complexity of any computed property that is not O(1).
- Prefer methods and properties to free functions.
- Follow case conventions. Names of types and protocols are
UpperCamelCase. Everything else is
- Methods can share a base name when they share the same basic meaning or when they operate in distinct domains.
- Choose parameter names to serve documentation.
- Take advantage of defaulted parameters when it simplifies common uses. Any parameter with a single commonly-used value is a candidate for a default.
- Prefer to locate parameters with defaults toward the end of the parameter list.
- Omit all labels when arguments can’t be usefully distinguished, e.g.
- In initializers that perform value preserving type conversions, omit the first argument label, e.g.
- When the first argument forms part of a prepositional phrase, give it an argument label. The argument label should normally begin at the
- Otherwise, if the first argument forms part of a grammatical phrase, omit its label, appending any preceding words to the base name, e.g.
- Label all other arguments.
- Label tuple members and name closure parameters where they appear in your API.
- Take extra care with unconstrained polymorphism (e.g.
AnyObject, and unconstrained generic parameters) to avoid ambiguities in overload sets.
Copyright © 2019 Weslie. All rights reserved.