Better Code Through Commenting

Commenting ones code is a fundamental principle of good programming. The benefits are clear. Functionality is more easily understood, with less of a learning curve for new employees who have better things to do than analyze your code. In an industry with a relatively high turnover rate, this becomes even more important. Ive come to realize, however, that the commenting of code can serve a more selfish, and perhaps a fundamentally more useful purpose.

When I initially approach an area of a project to focus on, my goal is usually to work all the way through to the most basic endpoint as quickly as possible, and then layer additional functional requirements on top of that. This gives me a framework in which testing can easily be conducted as new functionality is added. With this approach, commenting becomes the first step to the programming process, with the major concepts defined and organized by comment blocks, to be worked out later.

The advantage to this approach is that it lets the major aspects of a programatic concept be conceptualized by the developer in large brush strokes. This is particularly useful in the higher-level areas of a system, where a strictly object-based organizational scheme might not be terribly pragmatic.

There are some welcome side-effects as well. The human attention span can really only process about 5-9 distinct items or concepts simultaneously at any given point. So, by breaking out the problem clearly first, and then dealing with individual areas, one is able to consider with greater accuracy the implications of the particular task at hand. In addition, the final product will be organized and commented in such as way that clearly illustrates not just what the code does, but how the developer initially approached the problem. This, I have found, is much more illuminating to future programmers as they try to dissect how the code works.