** This is a work in progress, that mostly contains lots of good links **

It’s one of the hardest things you do a programmer and also one of the most important aspects of writing code. Code is read 10x more than it’s written so when you are writing you need to be very thoughtful of the future readers, which are yourself & others. You want your code to be very clear to readers, even if you are the only reader. Readability makes or break a project There has been plenty of times that I don’t look at a piece of code for months and come back and have to re-learn what I what I was doing.

An important principle for naming is to communicate intentions.

The process of thoughtful naming also help you to identify code smells. If you are having a hard time naming a class, it may do too many things and should be possbily broken down.

Purpose & Potential

There is this idea that people live up to their names, & derive meaning/purpose from their name. You should apply this notion of naming things to objects. Naming something gives it a purpose & meaning - it essentially creates it’s “definition”. If you name an object generically, it doesn’t have clear definiion, clear boundaries. Due to this lack of focus an object can quickly end up doing more than it should which lead be bad code smell.

Hints

Is there a physical object that can help describe

When you are struggling with naming something, created wordmaps, word graphs from the name or concept that you are starting with.

Tools

Using a thesarus helps you to find similar terms that may better communicate intent &/or context

Inversely, if you enter your variable or method on the link and it’s on the list then you probably shouldn’t use the name.

Seek

  • Names that reveal intent
  • class CommentModerator encapsulates logic for moderating comments
  • find_configs(directory) returns list of configs from a directory
  • is_risky_command(command) returns true/false of risk of command
  • Names that remove need for comments
  • Be consistent
  • To name things that correlate to the domain
  • Accurately describe the variable or method
  • Conciseness over verbosity
  • Use analogies & metaphors
  • Scalable patterns
  • Have some fun
  • Memorable

Avoid

  • Ambiguity
    • One letter or Short names
    • ls vs list
    • Don’t use a or bcz unless i in loop
  • Generic terms like Manager or Provider or words
    • class ServiceProvider ...
    • list = ['a', 'b', 'c']
    • process_data(d)
    • word = "word"
    • file_handle = open('output.log')
  • Uneeded abbreviations or prefixes/suffixes
    • WordPrcsr vs WordProcessor
    • Including type in variable listOfCats vs cats
  • Misleading names
    • words = [1, 2, 3]
    • has_word(sentence) # -> but returns 'string'
  • Methods or functions that describe how it works
    • query_mysql_users() vs get_users()
  • Cleverness
  • nuke(cache) vs flush(cache)
  • shun(user) vs ban(user)

Inspirations