Diese Präsentation wurde erfolgreich gemeldet.
Wir verwenden Ihre LinkedIn Profilangaben und Informationen zu Ihren Aktivitäten, um Anzeigen zu personalisieren und Ihnen relevantere Inhalte anzuzeigen. Sie können Ihre Anzeigeneinstellungen jederzeit ändern.

Naming guidelines for professional programmers

727 Aufrufe

Veröffentlicht am

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.

Veröffentlicht in: Technologie

Naming guidelines for professional programmers

  1. 1. @PeterHilton http://hilton.org.uk/ Naming guidelines for professional programmers @felienne www.felienne.com
  2. 2. 15 years as 
 the development team’s only native English speaker… 3@PeterHilton •
  3. 3. There are two problems in computer science… There’s only one joke, and it isn’t funny. Phillip Bowden 5@PeterHilton •
  6. 6. What does the computer science literature say 
 about naming? 10@PeterHilton •
  7. 7. http://hilton.org.uk/presentations/naming-guidelines
  8. 8. 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 •
  9. 9. Seeing is believing: the effect of brain images on judgments of scientific reasoning. Cognition. 2008 Apr;107(1):343-52.
  10. 10. Syntax guidelines (12)
  11. 11. Use naming conventions Follow the programming language’s conventions for names. ☹ appleCOUNT, apple_count X@PeterHilton •
  12. 12. 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 •
  13. 13. 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 •
  14. 14. 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 •
  15. 15. Articulate symbolic names X@PeterHilton •
  16. 16. 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 •
  17. 17. Only use one underscore at a time X@PeterHilton •
  18. 18. Only use underscores between words X@PeterHilton •
  19. 19. Limit name character length Keep name length within a twenty character maximum. ☹ foreignDomesticAppleCount X@PeterHilton •
  20. 20. 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 •
  21. 21. 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 •
  22. 22. 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 •
  23. 23. Vocabulary guidelines (10)
  24. 24. 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 •
  25. 25. 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 •
  26. 26. 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 •
  27. 27. 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 •
  28. 28. 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 •
  29. 29. 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 •
  30. 30. 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 •
  31. 31. 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 •
  32. 32. 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 •
  33. 33. 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 •
  34. 34. Data type guidelines (7)
  35. 35. 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 •
  36. 36. Use singular names for values Don’t pluralise names for single values. ☹ appleCounts X@PeterHilton •
  37. 37. Use plural names for collections Pluralise names for collection values, such as lists. ☹ remainingApple for a set of apples X@PeterHilton •
  38. 38. 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 •
  39. 39. 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 •
  40. 40. 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 •
  41. 41. 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 •
  42. 42. Class & method name guidelines (11)
  43. 43. 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 •
  44. 44. 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 •
  45. 45. 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 •
  46. 46. Rejected guidelines (10)
  47. 47. 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 •
  48. 48. 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 •
  49. 49. 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 •
  50. 50. Conclusion
  51. 51. 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 •
  52. 52. 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?
  53. 53. @PeterHilton http://hilton.org.uk/http://hilton.org.uk/presentations/