General Coding Philosophies

This article just lists some general coding philosophies that has guided me in how I design and write my code.

Source Code Answer “What” and “How”

The application source code answers what the code is doing.

• Diving a bit deeper in to self-documenting source code, the class, variable, and method/function names answer what the code is doing. The actual code inside the class and method/function answers how the code is doing what its name suggests.
• Analogously, I use class, file and function/method names like chapter titles. The main function is like a table of contents with these chapter titles. And if the reader needs to look up how the code is implemented, the reader can then dig deeper into the class, file, and function/method.
• The main idea is to avoid throwing all of the code at the reader at once. Instead, give the reader what they immediately need and then have him/her dig deeper if they need to.

Comments Answer “Why”

I try to use comments sparingly. If I have to explain what the code is doing, then this is an indication that I should simplify my code. If I am practicing self-documenting code properly, then comments can then be used to answer why the code is designed this way. For example, maybe a link to an article or a few sentences describing why a work-around was needed and when (and/or what event needs to happen before) it can be taken out or simplified.