Uploaded byPeter Hilton
Naming guidelines for professional programmers
The document outlines comprehensive naming guidelines for professional programmers, emphasizing the importance of naming in code clarity, maintainability, and bug prevention. It includes detailed suggestions, such as using descriptive names, adhering to programming conventions, and avoiding ambiguous or overly complex identifiers. Additionally, it poses research questions regarding the impact of naming on code quality and maintainability.
More Related Content
Similar to Naming guidelines for professional programmers
![A Primer on High-Quality Identifier Naming [ASE 2022]](https://cdn.slidesharecdn.com/ss_thumbnails/tutorialidentifiernaming-221010194443-15a389e4-thumbnail.jpg?width=640&height=640&fit=bounds)
Naming guidelines for professional programmers
- 1. @PeterHilton http://hilton.org.uk/ Naming guidelines for professionalprogrammers @felienne www.felienne.com
- 3. 15 years as the development team’s only native English speaker… 3@PeterHilton •
- 5. There are twoproblems in computer science… There’s only one joke, and it isn’t funny. Phillip Bowden 5@PeterHilton •
- 8.
- 9.
- 10. What does the computerscience literature say about naming? 10@PeterHilton •
- 11.
- 12. Why I talkabout 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.
- 15. Use naming conventions Followthe programming language’s conventions for names. ☹ appleCOUNT, apple_count X@PeterHilton •
- 16. Replace numeric suffixes Don’tadd 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 Onlyuse 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’tmake 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.
- 20. Name constant values Namewhat 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 oneunderscore at a time X@PeterHilton •
- 22. Only use underscoresbetween words X@PeterHilton •
- 23. Limit name characterlength Keep name length within a twenty character maximum. ☹ foreignDomesticAppleCount X@PeterHilton •
- 24. Limit name wordcount 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 withsuffixes 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’toverwrite 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.
- 28. Describe meaning Use adescriptive 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 aspecific 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 Usewords 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 Avoidbeing 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 largevocabulary 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 domainterms 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 differby 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 differby 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 differin 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 differphonetically 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.
- 40. Omit type information Don’tuse prefixes or suffixes that encode the data type. Avoid Hungarian notation and its remnants. ☹ isValid, dateCreated, iAppleCount 25@PeterHilton •
- 41. Use singular namesfor values Don’t pluralise names for single values. ☹ appleCounts X@PeterHilton •
- 42. Use plural namesfor collections Pluralise names for collection values, such as lists. ☹ remainingApple for a set of apples X@PeterHilton •
- 43. Prefer collective nounsfor 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 Consistentlyuse 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 namesthat 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 Booleannames 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 & methodname 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 Usea 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 Onlyuse 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.
- 52. Use long namesfor 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 identifiernames ‘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 identifiernames ‘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.
- 58. Conclusion 1. There arelots 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 (reverseQ&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.