Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Commenting
Commenting, the last of the four forms of good coding in this article, is one of the most important and often the most neglected.
Many developers consider documentation to be the "spawn of evil," and commenting is the first step toward documentation. Besides, many developers contend that their code is "self-document" (this translates to "do not touch my code unless you are smart enough to decipher my hacked code"). Not commenting is a good sign of lazy and unplanned code because adding commenting really only adds a few minutes of effort if there is a well-laid-out plan to structure the code. Another favorite of mine is developers who overuse naming conventions, as follows:
ThisModuleHandlesCreditWorthinessButDoesNotPerformCalculations
CheckingHowManyJobsAndHowManyPlacesApplicantHad
NotReallySureHowImportantThisIsButUsersWantThis
These modules become a bit cumbersome to use because they are called throughout the application. Try using names that are more concise and leave any details to the comments.
Personally, I always begin the code by first adding comments to each of the modules in the code that I believe will encompass the scope of functionality needed. This initially lays out how I will approach the building of the code and provides me with a good starting point instead of hacking together code until the darn thing works. Besides, I usually have a template for the comments that I can easily copy and paste and then fill out when I start. It usually looks like the following:
' - - - - - - D E T A I L - - - - - - ' Module: FormValidation ' Purpose: Check all fields are correct in application ' Author: Fenix Theuerkorn ' Date: 02/02/04 '- - - - - - H I S T O R Y - - - - - - ' 3/14/04, added check for valid postal code '
In addition, I add comments within the module where there are major sections of functionality. A good candidate is the beginning of any nested code because this is usually a major transition of programming flow with conditional checks and looping. This can be simply a short sentence or two to describe the code ahead. Again, I write my comments first before I code as I lay out my design for the module; this serves as a place marker for me to build my code.