All kinds of programmers acknowledge the difficulty of naming things, but relatively few use explicit naming guidelines. Various authors have published different kinds of identifier naming guidelines, but these guidelines do little to make naming easier, in practice. Meanwhile, professional programmers follow diverse conventions and disagree about key aspects of naming, such as acceptable name lengths. Although few teams write their own coding standards, let along naming guidelines, many teams use code review and pair programming to maintain code quality. These teams can use third-party naming guidelines to inform these reviews, and improve their coding style. This presentation introduces a set of naming guidelines that professional programmers can use in their work, consolidated from various sources.

1. @PeterHilton
http://hilton.org.uk/
Naming guidelines for
professional programmers
@felienne
www.felienne.com

3. 15 years as
the development
team’s only native
English speaker…
3@PeterHilton •

5. There are two problems
in computer science…
There’s only one joke,
and it isn’t funny.
Phillip Bowden
5@PeterHilton •

8. SUPERNAME

9. NAMINATOR

10. What does the
computer science
literature say
about naming?
10@PeterHilton •

11. http://hilton.org.uk/presentations/naming-guidelines

12. Why I talk about naming guidelines
1. We rely on naming to understand code
2. Bad names cause bugs
3. Good naming is critical for maintainability
4. Naming things is famously hard
5. Guidelines help us get better at naming
12@PeterHilton •

13. Seeing is believing: the effect of brain images on judgments of
scientific reasoning. Cognition. 2008 Apr;107(1):343-52.

14. Syntax guidelines (12)

15. Use naming conventions
Follow the programming language’s conventions for names.
☹ appleCOUNT, apple_count
X@PeterHilton •

16. Replace numeric suffixes
Don’t add numbers to multiple identifiers with the same
base name.
If you already have an employee variable, then a name like
employee2 has as little meaning as another_employee.
☹ employee2
X@PeterHilton •

17. Use dictionary words
Only use correctly-spelled dictionary words and
abbreviations that appear in a dictionary.
Make exceptions for id and documented domain-specific
language/abbreviations.
☹ acc, pos, char, mod, auth, appCnt
15@PeterHilton •

18. Expand single-letter names
Don’t make exceptions to using dictionary words for single-
letter names.
Use searchable names.
☹ i, j, k, l, m, n, t, x, y, z
16@PeterHilton •

19. Articulate symbolic names
X@PeterHilton •

20. Name constant values
Name what the constant represents, rather than its constant
value.
Don’t construct numeric constant names from numbers’
names.
☹ 3.142591, ONE_HUNDRED
X@PeterHilton •

21. Only use one underscore at a time
X@PeterHilton •

22. Only use underscores between words
X@PeterHilton •

23. Limit name character length
Keep name length within a twenty character maximum.
☹ foreignDomesticAppleCount
X@PeterHilton •

24. Limit name word count
Keep name length within a four word maximum, and avoid
gratuitous context.
Limit names to the number of words that people can read at
a glance.
☹ newRedAppleSizeType, myAppSizeType
17@PeterHilton •

25. Qualify values with suffixes
Use a suffix to describe what kind of value constant and
variable values represent.
Suffixes such as minimum, count and average relate a
collection of values to a single derived value.
☹ minimumAppleCount
X@PeterHilton •

26. Make names unique
Don’t overwrite a name with a duplicate name in the same
scope.
Adopt a convention that prevents ambiguity in which name
the programmer intended to refer to.
X@PeterHilton •

27. Vocabulary guidelines (10)

28. Describe meaning
Use a descriptive name whose meaning describes a
recognisable concept, with enough context.
Avoid placeholder names that deliberately mean nothing
more than a_variable.
☹ foo, blah, flag, temp
19@PeterHilton •

30. Be precise
Identify a specific kind of information and its purpose.
Imprecise words might apply equally to multiple identifiers,
and therefore fail to distinguish them.
☹ data, object
X@PeterHilton •

31. Choose concrete words
Use words that have a single clear meaning.
Like imprecise words, abstract words might apply equally to
multiple identifiers.
☹ Manager suffix, get prefix, doIt
21@PeterHilton •

32. Use standard language
Avoid being cute or funny when it results in a name that
requires shared culture or more effort to understand.
Deliberately meaningless names require the reader to
understand some implicit context.
☹ whack instead of kill
X@PeterHilton •

33. Use a large vocabulary
Use a richer single word instead of multiple words that
describe a well-known concept.
Use the word that most accurately refers to the concept the
identifier refers to.
☹ CompanyPerson
😀 Employee, Director, Shareholder
22@PeterHilton •

34. Use problem domain terms
Use the correct term in the problem domain’s ubiquitous
language, and only one term for each concept, within each
bounded context.
Consistently use the correct domain language terms that
subject-matter experts use.
☹ Order instead of Shipment, in supply-chain
X@PeterHilton •

35. Make names differ by more than 1-2 letters
Don’t use a name that barely differs from an existing name.
Avoid words that you will probably mix up when reading the
code.
☹ appleCount vs appleCounts
X@PeterHilton •

36. Make names differ by more than word order
Don’t use a name that only differs from an existing name in
word order.
Don’t use two names that both combine the same set of
words.
☹ appleCount vs countApple
X@PeterHilton •

37. Make names differ in meaning
Don’t use names that have the same meaning as each other.
Avoid names that only differ by changing words for their
synonyms.
☹ input/inputValue, recordCount/numberOfRecords
X@PeterHilton •

38. Make names differ phonetically
Don’t use names that sound the same when spoken.
Aim to write code another programmer could write down
correctly if you read it out loud.
☹ wrap/rap
23@PeterHilton •

39. Data type guidelines (7)

40. Omit type information
Don’t use prefixes or suffixes that encode the data type.
Avoid Hungarian notation and its remnants.
☹ isValid, dateCreated, iAppleCount
25@PeterHilton •

41. Use singular names for values
Don’t pluralise names for single values.
☹ appleCounts
X@PeterHilton •

42. Use plural names for collections
Pluralise names for collection values, such as lists.
☹ remainingApple for a set of apples
X@PeterHilton •

43. Prefer collective nouns for collections
If a collection’s type has a collective noun, in the name’s
context, use it instead of a plural.
☹ appointments (replace with calendar), pickedApples
(replace with harvest).
26@PeterHilton •

44. Use opposites precisely
Consistently use opposites in standard pairs with naming
conventions.
add/remove, begin/end, destination/source, create/
destroy, first/last, insert/delete, get/release,
lock/unlock, minimum/maximum, increment/decrement,
next/previous, old/new, open/close, put/get, show/
hide
X@PeterHilton •

45. Use Boolean names that imply true or false
Use names like done or found that describe Boolean values.
Use conventional Boolean names, possibly from a code
conventions list.
☹ status for e.g. started
X@PeterHilton •

46. Use positive Boolean names
Don’t use negation in Boolean names.
Don’t use names that require a prefix like not that inverts
the variable’s truth value.
☹ notSuccessful
X@PeterHilton •

47. Class & method name
guidelines (11)

48. Class name guidelines
1. Use a noun-phrase name
2. Use a name that allows all possible states
3. Choose a name consistent with possible values
28@PeterHilton •

49. Method name guidelines
Use a verb-phrase name
Don’t use get, is or has prefixes for methods with side-
effects
Only use get, is and has prefixes for methods that only
peform field access
Only use get prefix for field accessors that return a value
Only use is and has prefixes for Boolean field accessors
29@PeterHilton •

50. Method name guidelines
Only use set prefix for field accessors that don’t return a
value
Only use validation verbs for methods that provide the
result
Only use transformation verbs for methods that return a
transformed value
30@PeterHilton •

51. Rejected guidelines (10)

52. Use long names for long scopes
‘When you give a variable a short name like i, the length
itself says something about the variable - namely that the
variable is a scratch value with a limited scope of operation.’
Steve McConnell - Code Complete, Microsoft Press (1993)
i.e. encode a variable’s scope in its name length, which
contradicts other guidelines and encourages bad naming
32@PeterHilton •

54. Use short identifier names
‘avoid an identifier name shorter than eight characters,
excluding: i, j, k, l, m, n, t, x, y or z’
Phillip Relf - Achieving Software Quality through Source Code
Readability (2004)
34@PeterHilton •

56. Use short identifier names
‘One-character variable names should be avoided except for
temporary “throwaway” variables. Common names for
temporary variables are i, j, k, m, and n for integers; c, d,
and e for characters.’
Sun Microsystems - Code Conventions for the Java™
Programming Language (20 April 1999)
36@PeterHilton •

57. Conclusion

58. Conclusion
1. There are lots of guidelines to use
2. There are also OOP and FP guidelines
3. Some are more obvious than others
4. Some are difficult to follow
X@PeterHilton •

59. Further research (reverse Q&A)
38@PeterHilton •
1. How much does naming really affect maintainability?
2. Which naming guidelines have the most positive impact?
3. Does better naming reduce the need for code comments?
4. Can we measure name quality or guideline effectiveness?
5. Could we do a cost-benefit analysis of naming guidelines?
6. Do pair and mob programming improve naming quality?
7. Which techniques improve programmers’ naming skills?
8. How might we improve tool support for naming?

60. @PeterHilton
http://hilton.org.uk/http://hilton.org.uk/presentations/