Over at my old job, I had an epiphany and I was wanting to share my thoughts on it to the readers.
Reading good code is like reading a good book.
As stated in the title, it’s called READING code not deciphering code. When you read a book, there’s nothing more annoying than having to jump back and forth between chapters to remember who killed who or who did what. A good book should have a smooth transition between chapters. The flow of it should be fairly straight forward, otherwise it becomes a nuisance to read and gets left on the bookshelf. Code should not be any different.
When I worked support, I hated jumping back and forth in code to figure what the “temp” variable was used for or the why the function “LoadData” was 400 lines long. Come on people! Code should flow.
If you need a temporary variable, then give it the value it actually holds, but try to keep the word “temp” out of the picture. This naming convention will keep you from writing any and everything to a single “temp” variable and will save your support people from pulling their hair out. Any variable declared in a function is considered “temporary” by definition.
Also, don’t forget about your counters and/or sentinels. Let’s say you’re looping through an array of employee names. Well, instead of saying the following:
for( int i = 0; i &lessthan len(employeeNames); ++i )
Print(employeeNames[i]);
Try saying this:
for( int employee = 0; employee &lessthan len(employeeNames); ++i )
Print(employeeNames[employee]);
Since you’re essentially going through a different employee to grab their name, why not state such? In .NET, there is the “foreach” construct that forces you to use a more object oriented approach to looping through collections.
Now for functions… Name your functions according to exactly what they do. If your function name is too long, chances are you need to break up your function into other smaller functions. If it’s too short, you’re probably not giving it a proper name. A function should only perform one operation. If you’re one of those types of people that like to write “bulk” functions, then at least make it readable. Keep the abstraction simple.
function void Cleanup()
{
ClearEmployeeNames();
ClearManagerNames();
//etc...
}
So, in closing, I hope I have saved at least one support person the headache that they already endure on a day to day basis. Their job is tough already, do not make it any harder on them by making your code impossible to read. Enjoy!
