Naming Matters: Enhancing Code Readability and Maintainability

Hey, fellow developers! Today, we will focus on a big aspect of programming that has less to do with tools or efficiency of code, but rather enhacning the ability to maintain it, making it more clear for other developers and overall creating a welcoming occasion everytime someone jumps into your codebase.

Naming Matters: Enhancing Code Readability and Maintainability

Most people when questioned about what makes a codebase good, rarely include naming in their answer. Naming conventions might not be the first thing that comes to mind, yet they play an important role in the overall quality of your codebase and your skills as a developer.

By enploying well-defined variables and functions we can greatly improve the readability and maintainability of our codebase, making it easier to understand and therefore debug, collaborate and enhance.


What is the issue with the above code?

Steve recently made this wonderful tweet which inspired this blog post in which he asks a very simple question.

What’s wrong with the object properties?

int Duration
int Timeout

It is a great segue to our main topic: naming matters! In the example above, the properties seem to not have any spelling mistakes. It is obvious that one is the duration and the other is timeout; they use normal C# syntax. However, the issue is understanding what those variables actually hold.

Let’s take Duration, for example. Most people would assume it is in seconds, or hope that the overall context (such as the class name) will guide us in understanding the unit of measurement that Duration is in. Unfortunately, I think this is a very common issue. I have often had to fill in different Duration fields in YAML files where the context does not provide enough clarity regarding the unit of measurement.

What should we do?

In the case above, the suggested approach would be to include the unit of measurement in the property name. DurationInSeconds comes quickly to mind or DurationSeconds if you wish to be a bit more concise. By following this approach, we can quickly denote the unit of measurement and still maintain all the previous knowledge regarding the property.

There is definitely a downside that names can start becoming longer than some like; however, code is there to be read. Longer variable or property names can lead to slightly higher memory usage and code size, yet the costs of such an enhancement are minimal in comparison to passing milliseconds instead of seconds and spending a few hours trying to find the bug in your codebase.

If there are such concerns, the program is most likely running on limited hardware, and there are other ways that allow the compiled output to be minimized to remedy such effects.

Best Practices

Below are some best practices to follow when deciding on the name of a variable or function. As always, these are best practices and should not be used dogmatically.

  • Be Descriptive: Names should clearly describe the purpose of the variable or function. We should avoid generic names like Duration or worse Data
  • Keep It Concise: Being descriptive is important, however too long of names can make coder harder to read.
  • Use Consistent Style: Consistency, consistency, consistency. Use a consistent naming style through your codebase, be it camelCase, scane_case or other.
  • Avoid Abbreviations: It is safer to use full words instead of abbreviations to avoid any confusion.
  • Context Matters: The context of a variable or function should always be taken into account when naming them. Local variables can have shorter names, while global variables should be more descriptive.

Conclusion

Take the time to use explicit and proper naming in your codebase is a small inestment that pays off in the long term both for your personal development and for the application. Next time you are writing code, remember that naming matters!

Subscribe to the Newsletter