Naming, precise functions and streamlined variables.

We all struggled with the naming,
Or struggling.

Readable is one of the most important things while developing a large system. Your code is always going to be changed by someone else after commit. And that might even be the future you, so give yourself a hand by naming the cool way to make everything easier.

The big question is, how?
Divide and conquer is the go-to solution while fixing complex issues.
Let’s see the purpose of “good naming” should be able to present
the concept of the things behind the name.

First, it supposed to be accurate, do some surveys to find the right word and convention would be really helpful. Especially the convention, if it’s commonly used by engineers or the team/system it would be a better name even it seems to be a wrong choice in the dictionary. Because it’s a known knowledge and could be read more instinctively.

Second, it supposed to be precise, and third, it supposed to be streamlined.
Wait, it seems we got a conflict here!
How’s that even possible to be precise and streamlined in the meantime?

It does impossible.

We made a choice after reviewing the pros and cons.
We would focus on precise while naming a function and focus on streamlined while naming a variable.

We need the precise description for better understanding the high-level concept of the function like “get_the_reader_names_who_read_this_article”.

Class DifferentNamingStyle():
  def get_the_reader_names_who_read_this_article(self):
    ...
  def get_reader_names(self):
    # Get get the reader names who read this article
    ...

Another option is to have a long comment somewhere in the code, but the code itself is always the best place to document.

Compare the following:

def say_hi_to_my_readers(self):
  readers = self.get_reader_names()  # Who are they??
  ...
def say_hi_to_my_readers(self)
  readers = self.get_the_reader_names_who_read_this_article()
  ...

The code is the first place you would read, and in most cases, that might be the only place you would read.

Then how about the variables? We don’t care about the precise anymore?
The answer is no, it just we put the streamlined before precise while naming a variable.
Because a variable would never come from nowhere. You must initialize it from either a class or a function.

def oh_i_need_some_reader():
  new_reader = Reader()
  readers = get_the_reader_names_who_read_this_article()

So there would always have a clue for you to figure out what are those variables. (Don’t tell me your code paragraph was too long to find the place the variable was initialized, it’s your own fault 😉)

And back to streamlined, there is a simple reason, it was too easy to mistake between multiple long-named variables.

def do_something_with_readers(): 
  
  potential_readers_who_read_the_keith_blog = get_potential_readers_who_read_the_keith_blog()
  potential_readers_who_read_the_tim_blog = get_potential_readers_who_read_the_tim_blog()
  # Say hi to the readers of Keith
  say_hi(
    "hi, since you know Keith ...",      
    potential_readers_who_read_the_tim_blog
  )

Did you see what’s wrong? If not, that’s what we’re terrified about the long variable names. Also, the efficacy of representing the meaning is duplicated with the function name in the sample code.

potential_readers_who_read_the_keith_blog = get_potential_readers_who_read_the_keith_blog()

As we know, we should avoid doing the same thing in a different place, which might potentially cause more unexpected bugs. While facing this situation, to have a short and clean name is more recommended.

The bottom line is, you should always think about all three tips to have a better naming, but when they got a conflict, we do have a certain recommendation for different situations:

- Precise over streamlined(Name as long as you want): Functions and Classes
- Streamlined over precise(Try to keep it short): Variables

Just like other principles, it might not fit all cases. But in most situations, if you found yourself cannot follow the tips, it might be meaning you’re doing it wrong. Consider reorganization your classes, functions or even variables.

Any thoughts? Welcome to bring discussions or just leave us a line here!