Naming issue (Prefix only issue)

Prefix only issue.md

Prefix only issue

The general goal of your codebase should be to make it as easy to understand as possible.

Easy to understand results in:

• less bugs due to insufficient knowledge (because over time you might forget some parts)
• implicit understanding without the need for comments (less time spent reading comments)
• no need for documentation or intruduction to the project, since it's faster to just look at the code
• in case everyone dies, rookie can just come in and easily continue on

Thus we must learn from our and others' mistakes and prevent them from ever happening again. We shall always strive for perfection and maximum readability.

"Those who fail to learn from history are doomed to repeat it" - George Santayana

Real life example #1

I was working on a raycaster for college project. Inside one method I had this:

var ray = ...
var rayReflected = ...
var rayToLight = ...

if(ray.dot(rayToLight) > 0) ...

I spent several hours debugging this, only to find that it should have instead been:

if(rayReflected.dot(rayToLight) > 0) ...

While reading through the code (many times) I always stopped at the prefix and assumed it is right. I did the mistake of using only prefix alone while some other variable used both the same prefix and concretization in its name. After finding this I've renamed ray -> rayOriginal so I never make this mistake again.

Real life example #2

Web application. Architecture: Controller <-> Recording <-> Backend (database)

Our recording has these two states:

enum DebugRecording { 
  None,
  Save,
  Load,
};

• None = nothing will happen, recording will be disabled, maybe better name would be Disabled, but None is clear enough.
• Save = Backend <-> Controller communication will be recorded to file and saved.
• Load = Backend <-> Controller communication will be faked and data will be loaded from previously saved file, if data are not found, Backend is used.

Eases debugging of bugs only reproducible on customer environments (we record it, then playback locally)

But now your SSA (Senior Software Architect) comes and does this (adds LoadOnly):

enum DebugRecording { 
  None,
  Save,
  Load,
  LoadOnly,
};

Right, so... Load and LoadOnly, what is the difference ?

Load is was turned into prefix. The prefix is used both alone and with concretization. Now we are confused what is the difference between Load and LoadOnly. Is it an inheritance relationship, inside enum ? Does Load do the same as LoadOnly ? Is LoadOnly special case of Load ?

The problem here is the naming issue (specifically prefix only issue). SSA took name (Load), modified the behavior of it and turned it into prefix different behavior (LoadOnly).

If one is to understand the difference between Load and LoadOnly he has to delve into the code and figure out the difference, one has to waste some time and money.

If it was instead name this way:

enum DebugRecording { 
  None,
  Save,
  LoadOrUseBackend,
  LoadOrThrowException,
};

It is immediately clear what it means and there is no room for confusion.

By naming it this way:

• We prevented confusion from naming.
• We saved others' time and our company's money.

Conclusion

• never use prefix alone
• refactor always

In Visual Studio you can easily rename all occurences of variable name by doing Edit -> Refactor -> Rename. There is even shortcut for it, remember it, use it, alot.