I’ve been refactoring my project for some weeks now, and one of the things that has consumed most of my time has actually been choosing good names for variables, functions and classes. Although at first glance it doesn’t seem a critical aspect of the code, well-named variables ensure readability of the code. Which, if you intend to release you source to the world, can make the difference between people using your code and keeping a repository that no one will ever visit.
I became really aware of this matter reading the post about the Doom 3 source code I linked here some time ago. One of the comments that caught my eye was:
“Code should be self-documenting. Comments should be avoided whenever possible. Comments duplicate work when both writing and reading code. If you need to comment something to make it understandable it should probably be rewritten.”
After years of being taught that all code must be well documented, I couldn’t understand how avoiding comments could be considered a good programming practice. But subsequent reading of Clean Code, by Robert C. Martin, made things much clearer. As a good software designer, functions have to be simple and single-purposed and names must be intention-revealing, meaningful, pronounceable, searchable, unambiguous and, while complying with all the previous, as simple as possible. Which is not an easy at all.
But when all that is achieved, for sure no comments are needed: The code is perfectly readable by itself and the purpose of every function and variable is perfectly clear.