Writing Word Macros, Second Edition

Programming Style

The issue of what constitutes good programming style is, of course, subjective, just as is the issue of what constitutes good writing style. Probably the best way to learn good programming style is to learn by example and to keep the issue somewhere in your consciousness while programming.

This is not the place to enter into a detailed discussion of programming style. However, in my opinion, the two most important maxims for good programming are:

• Fill your programs with a lot of meaningful comments.

• When in doubt, favor readability over cleverness or elegance.

Comments

It is impossible to overstate the importance of adding meaningful comments to your programs—at least any program with more than a few lines.

The problem is this: good programs are generally used many times during a reasonably long lifetime, which may be measured in months or even years. Inevitably, a programmer will want to return to his or her code to make changes (such as adding additional features) or to fix bugs (errors). However, despite all efforts, programming languages are not as easy to read as spoken languages. It is just as inevitable that a programmer will not understand (or perhaps even recognize!) code that was written several months or years earlier and must rely on carefully written comments to help reacquaint himself with his own code. (This has happened to me more times that I care to recall.)

Let me emphasize that commenting code is almost as much of an art as writing the code itself. ...