Pages

Monday, February 20, 2012

15 Best Practices of Variable & Method Naming






  1. Use short enough and long enough variable names in each scope of code. Generally length may be 1 char for loop counters, 1 word for condition/loop variables, 1-2 words for methods, 2-3 words for classes, 3-4 words for globals.
  2. Use specific names for variables, for example "value", "equals", "data", ... are not valid names for any case.
  3. Use meaningful names for variables. Variable name must define the exact explanation of its content.
  4. Don't start variables with o_, obj_, m_ etc. A variable does not need tags stating that it is a variable.
  5. Obey company naming standards and write variable names consistently in application: e.g. txtUserName, lblUserName, cmbSchoolType, ... Otherwise readability will reduce and find/replace tools will be unusable.
  6. Obey programming language standards and don't use lowercase/uppercase characters inconsistently: e.g. userName, UserName, USER_NAME, m_userName, username, ...
    • For example for Java, 
      • use Camel Case (aka Upper Camel Case) for classes: VelocityResponseWriter
      • use Lower Case for packages: com.company.project.ui
      • use Mixed Case (aka Lower Camel Case) for variables: studentName
      • use Upper Case for constants : MAX_PARAMETER_COUNT = 100
      • use Camel Case for enum class names and Upper Case for enum values.
      • don't use '_' anywhere except constants and enum values (which are constants).
  7. Don't reuse same variable name in the same class in different contexts: e.g. in method, constructor, class. So you can provide more simplicity for understandability and maintainability.
  8. Don't use same variable for different purposes in a method, conditional etc. Create a new and different named variable instead. This is also important for maintainability and readability.
  9. Don't use non-ASCII chars in variable names. Those may run on your platform but may not on others.
  10. Don't use too long variable names (e.g. 50 chars). Long names will bring ugly and hard-to-read code, also may not run on some compilers because of character limit.
  11. Decide and use one natural language for naming, e.g. using mixed English and German names will be inconsistent and unreadable.
  12. Use meaningful names for methods. The name must specify the exact action of the method and for most cases must start with a verb. (e.g. createPasswordHash)
  13. Obey company naming standards and write method names consistently in application: e.g. getTxtUserName(), getLblUserName(), isStudentApproved(), ... Otherwise readability will reduce and find/replace tools will be unusable.
  14. Obey programming language standards and don't use lowercase/uppercase characters inconsistently: e.g. getUserName, GetUserName, getusername, ...
    • For example for Java, 
      • use  Mixed Case  for method names: getStudentSchoolType 
      • use  Mixed Case  for method parameters: setSchoolName(String schoolName)
  15. Use meaningful names for method parameters, so it can documentate itself in case of no documentation.

18 comments:

  1. +1 for using meaningful names. This is so helpful for being able to understand what the code is trying to do. If you use meaningful names, you rarely have to add in apologies (sometimes called comments).

    ReplyDelete
  2. Another +1 for meaningful names.

    Also, I'd avoid strict standards on how many words you should use in methods etc (1st rule.) Doesn't look like you follow the rule in any case (see points 13 and 14.)

    ReplyDelete
    Replies
    1. Word counts are not strict standards, just general approximate suggestions. Also 13 & 14 doesn't related with 1st rule, it is about variable naming.

      Delete
  3. What is most important in any convention is consistency. if you follow one convention in one part and other in other part no matter how good convention is it loses its benefit. consistency brings readability and predictability.You may like 10 Code comments best practices

    ReplyDelete
  4. oh man, did you make all this up on your own?

    ReplyDelete
  5. What about naming of vars that have acronyms in the name?

    i.e.

    myXMLVariable
    myXmlVariable
    myxmlVariable

    ReplyDelete
    Replies
    1. I think myXMLVariable is the most suitable one, because acronyms are written uppercase in general. But myXmlVariable may also be used. myxmlValue is unacceptable.
      The important things is consistency here. Choose one of the first two and use it consistently in every class of the application.

      Delete
  6. The size of the project matters. A thousand line stand-alone app can have single character globals.

    ReplyDelete
  7. I disagree with you about using _ in variable names. In my opinion it makes code far more readable.

    ReplyDelete
  8. This is fine for java but the python PEP 8 standards require underscores in between words for variable names unless lower camel case is already being used.

    ReplyDelete
  9. I introduce this post on my blog by translation into Japanese. Thanks!
    http://d.hatena.ne.jp/suginoy/20120226/p1

    ReplyDelete
    Replies
    1. Thanks for the useful translation.

      Delete
  10. 4. ... tags which states it is a variable. Is "state" the verb?. "tags" is plural. I'm confused.

    ReplyDelete
  11. This comment has been removed by the author.

    ReplyDelete
  12. This comment has been removed by the author.

    ReplyDelete
  13. 포스팅 잘 봤어요. 앞으로 더 좋은글 부탁드려요!

    ReplyDelete