Adhering to consistent and descriptive naming conventions is an often overlooked task. It is well documented in academic literature that good naming conventions are correlated with higher program comprehension and fewer bugs. Moreover, well-named classes, functions and constants give developers the ability to skim a large file with maximal comprehension; developers then deliver features and bug fixes swiftly with fewer errors. Conversely, poorly named classes and functions may not be descriptive enough to communicate their utility resulting in bug ladden code and, on occasion, accidental duplication of existing functionality.
Principles of Effective Naming
- Clarity always trumps brevity. It is not necessary to abbreviate objects with long names. Write them out and leave no doubt!
- Each word in a name conveys indispensable information about a property, function or object.
- Names should never be self referential.
- All names are written in camelCase. The first letter of a name is lowercase, all words that follow begin with an uppercase letter.
Naming Classes, Protocols, Methods and Properties
All class names should include a noun that clearly describes what the class and its properties and methods collectively achieve.
Protocols are to be named based upon how they organize behaviours. A class which is the singular expression of a protocol should have the same name as the protocol it conforms to. However we can have protocols that enforce definitions on multiple classes. In this case, to ensure a protocol is not confused with a class it is a common convention to use the Gerund form (…ing).
Apple has popularized multiple conventions for the naming of methods and encourages developers to employ these guiding principles to create more reliable products for the App Store. Methods that represent actions must begin with a verb (e.g. buildConstraints, displayLoadingIndicator). Beware of auxiliary verbs such as do-or-does which are not descriptive of a method’s utility and only serve to compromise brevity. Additionally, developers should avoid placing adverbs or adjectives before a verb. For weak type parameters (e.g. Any, NSObject) proceed the parameter with a noun describing its role. Lastly, always prefer methods whose use sites can be read like a well written sentence.
Properties should be named as stated by the function of the data stored and not by type. There are three forms of a property name which together cover the universal set of cases: noun, isAdjective, and verbObject (e.g. phoneNumber, isHidden, dismissMenu). Often developers mistakenly use the participle of a verb when naming properties (e.g. menuDismissed); these identifiers are misaligned with Apple’s recommendations.
Want to determine if your project is poorly named? Do you see the need for comments? If so, you probably need to set aside some time for renaming. Good naming should make comments redundant. Nonetheless, under all circumstances if you think of more appropriate names for your objects after naming them go ahead and refactor. Your colleagues will thank you for it!