Use Informative Names

Ben Cook • Posted 2020-05-18 • Last updated 2021-03-24

You should write code with humans in mind. Future developers (including you) should be able to understand a block of code quickly. It’s not easy to write complex code that can be easily understood, but one thing that definitely helps is using informative variable and function names.

There aren’t a lot of hard and fast rules here, but adopting some conventions does help. Some things to keep in mind:

  • Avoid single-letter variable names unless they’re obviously part of a formula. Names like ‘x’, ‘y’ and ‘t’ can make sense but don’t overdo it. When in doubt, write it out.
  • Spell names all the way out (e.g. use row_index instead of row_idx).
  • Put verbs in your function names (e.g. normalize_inputs() instead of normalization())
  • Pay attention to the casing conventions. In Python, that means lower_case_with_underscores for variables and functions and PascalCase for classes. In JavaScript, you should use camelCase for variables and functions.

This all might sound nit picky. Indeed, comments about these patterns are usually prefaced by “nit” in code reviews (e.g. nit: please spell this variable name all the way out). But understandable code is a big deal! And lots of small things add up to improve overall code quality.