Documenting Your Code

Let me start off by saying this: Always, always, always document your code.  This is such an important topic, that I decided to put it before all other requirements for good code.  You may not be the only one who needs to work with it, or you could forget how you wrote it.  Either way, documenting will make your life much easier.  With that being said, there are several ways of documenting your code.  Each method has its benefits and its difficulties.  What you will find is that the most effective method is a combination of all of them.

Self Documenting Code

The easiest and most beneficial documenting technique is using what I call ‘Self Documenting Code’.  Basically, this is where you would pick meaningful variable and function names.  Which looks better?

           $tem1 = “SELECT * FROM data”;

        $ar1 = getres($tem1);

            Or

                                           $sql = “SELECT * FROM data”;

                                $result = ExecuteQuery($sql);

In this example, $tem1 holds the query code.  By changing $tem1 to $sql, you have given meaning to the variable.  Now, you can just look at that variable and tell it hold some kind of query.  The next change comes in the $ar1 variable.  Again, $ar1 is meaningless whereas $result has a very distinct meaning.  Finally, the function getres() may appear at the time to be obvious, it could also hold many other meanings.  Could it mean get result, get resolution, get recipes, etc?  By changing it to something more meaningful in this setting, such as ExecuteQuery(), you now take all ambiguity out of the code.  The first piece of code is simple enough for a programmer to guess what it does, but the latter code requires no guess.  Even a novice programmer can look at the second piece of code and tell exactly what it does.

This technique is extremely powerful because of its simplicity.  It requires almost no additional effort on the part of the programmer, and consumes almost no additional resources (disk space, memory, etc).  If you can consistently use meaningful names, you’ve already won half the battle as far as documentation.  I do have one piece of caution with this, be careful not to rely on this method as your only piece of documentation.  This will quickly lead to problems, as similar sounding functions can have vastly different meanings.  With that being said, on to the inline documentation style.

Inline Documentation

Inline documentation adds a great deal of meaning to a block of code without adding too much effort on the part of the programmer.  Basically, all that you need to do is add commented text above any part of code that you feel needs commenting.  If you feel the code is self explanatory, then it probably does not need comments.  If, however, the code can be confused in any way, add a comment.  The following is an example of an inline comment in PHP.

// Check whether a user is an administrator

// $user_id is the user id of the current user

// returns true if is admin, false if not

Function is_admin($user_id) { …

The first line of the inline comment should always be the purpose of the function/code block.  In this example, the function is quite simple, but the idea is sound.  Then you can see that the input variable, even if simple, should ALWAYS be listed and qualified.  Finally, always list ALL POSSIBLE OUTPUTS of the function/code block.  While with a true/false function such as is_admin() this is trivial, when you start getting functions that return different results based upon inputs or errors, having all possible results listed (and their meanings) becomes a great help in expanding and understanding your code. 

Inline documentation is extremely easy to do, and does not take that much extra time to add while you are writing the code.  While this method does add to the disk space requirements (Hey, storage is cheap, programmers are not), it does not normally detract from the runtime performance of the program.  Inline documentation coupled with self documenting code is usually the only documentation that most non-professional (and some professional) programmers will ever need. 

External Documentation

While this book is not intended to be for the enterprise developer, I do feel that it is necessary to touch on this topic.  External documentation is a method where documentation (at least partially) is moved outside of the program, or in some cases is simply elaborated on outside of the program.  This is a really useful technique for released classes (such as a database connector class that can be used over and over), and usually the only technique for APIs where other programs are going to be interfacing with your own. 

This documentation should focus more on how to use the program (inputs and outputs of functions) and less on how the program was written (this is the point of a function, to eliminate the need for this information).  Note that you still need to document the mechanics of your code.  The best method of documentation combines all three that we have talked about here; Self documenting code for readability, inline documentation for mechanics, and external documentation for functionality.  Like I said before, you probably won’t need to use external documentation unless you are working on a large project, or want someone else to interface with your code.