Meaningful Names – Clean Code

“If a name requires a comment, then the name does not reveal its intent”

  • Write explicit code – naming variables and methods can reveal the entire intent of the code

  • Avoid using words that would be confusing like “List” as they refer to programming types and could be misleading : accountList should be accounts

  • Avoid using characters that look like numbers i and L or capital o

  • disinformative vs noninformative

    • noise words “data” “info” – noninformative
  • Types should almost never be in a name “table” “string” “object”

  • Names should be distinguished so a user can look at them and understand the differences

  • Use pronounceable names

  • Use searcheable names – longer names trump shorter names

  • Author’s pref – single letter names should only be used as local variables inside small methods – length of the name should correspond to the size of its scope

  • Avoid encoding names

  • Avoid Hungarian Notation with typing as part of the variable name – simply not needed nowadays

  • Stop prefixing member (instance) variables with m_ or _

  • Decorating Interfaces vs Classes with a prefix / suffix – opinion – he prefers

    • ClassImp or vs IType
  • Don’t force someone to map variable names in their mind – n = username…smart programmer vs professional programmer – clarity is king

  • Class names should be nouns – English 101 – NOT VERBS

  • Method names should be verbs

  • Use get, set, is – javabean standard

  • When constructors are overloaded, use static factory methods with explicit names – liked this one, possibly make the constructors private

  • Don’t get cute with naming by means of jokes (inside or well known)

  • Use consistent naming – Get, Set, Controller – makes it easier to understand and code various parts of an application

  • Avoid puns – add for a collection vs add for setting a value – two different meanings with the same name

  • Use technical names such as pattern names or CS terms in your names – other programmers will understand them better than the problem domain in some cases

  • Fall back to the problem domain for a name if there is no suitable technical name

  • Adding context to naming can clarify their use – prefixes can work but putting variables into classes may work out better

Tip: Use meaningful names

  • Be descriptive and imply type – E.g. for booleans, you can prefix with is_ or has_ to make it clear it is a condition. You can also use part of speech to imply types, like verbs for functions and nouns for variables.

  • Be consistent but clearly differentiate – E.g. age_list and age is easier to differentiate than ages and age.

  • Avoid abbreviations and especially single letters – (Exception: counters and common math variables) Choosing when these exceptions can be made can be determined based on the audience for your code. If you work with other data scientists, certain variables may be common knowledge. While if you work with full stack engineers, it might be necessary to provide more descriptive names in these cases as well.

  • Long names != descriptive names – You should be descriptive, but only with relevant information. E.g. good functions names describe what they do well without including details about implementation or highly specific uses.

Writing Clean Code: Nice Whitespace

Tip: Use whitespace properly

  • Organize your code with consistent indentation – the standard is to use 4 spaces for each indent. You can make this a default in your text editor.
  • Separate sections with blank lines to keep your code well organized and readable.
  • Try to limit your lines to around 79 characters, which is the guideline given in the PEP 8 style guide. In many good text editors, there is a setting to display a subtle line that indicates where the 79 character limit is.

“Hardest thing about choosing good names is that it requires good descriptive skills and a shared cultural background”

For more guidelines, check out the code layout section of PEP 8 in the notes below.

 

Writing Clean Code: Nice Whitespace

PEP 8 guidelines for code layout

sasindia

Leave a Reply

Your email address will not be published.