03. Commenting

A “comment” or “remark” is simply you writing stuff in your source code that doesn’t get seen by the compiler, browser or program generator. All programming languages provide a means (and sometimes multiple means) of commenting, here are a few examples:

HTML Comment
   <!-- this is a block comment -->

CSS Comment
   /* this is a block comment */

PHP/Java/JavaScript/C++ Comment
   /* this style of comment is very common...
      note that it can span multiple lines */
   // this comment excludes the rest of the line

VB.NET Comment
   ' this comment excludes the rest of the line

Once again there are no set rules on how you should comment but these guidelines will help you produce useful comments:

  • Comment for a n00b: Don’t write comments that only someone with extensive knowledge of the language you’re using would understand.
  • Don’t comment the obvious: We all know that “i = i + 1” increments ““, no need to comment that…but we may not know why this incrementing was necessary?
  • Break your code into logical blocks: Use comments to break the source code up into logical blocks. Much like white space, comments can drastically improve the readability of your code.
  • Be consistent: Don’t change your commenting style throughout your source code, remember that readability is paramount!

With the above ideas in mind, one technique that you may find helpful is to produce comments that act as a form of pseudocode required to solve the problem. That way you simply convert your comments into code as you program.

Consider the following pseudocode for some code that needs to be executed when a webpage has loaded:

// WHEN THE PAGE HAS LOADED
   // DECLARE ANY GLOBAL VARIABLES
   // LOAD THE USERS NAME INTO THE USER FIELD
   // LOAD THE LIST OF JOBS INTO THE JOB LIST
   // CREATE THE TABLE OF EQUIPMENT
   // RESET THE PAGE SO ALL FORM ITEMS ARE BLANK

Now that the logic is mapped out, we can convert this to code and create sub-procedures or functions as required, here’s a JavaScript/jQuery implementation:

// WHEN THE PAGE HAS LOADED
$(document).ready(function() {

   // DECLARE ANY GLOBAL VARIABLES
   var num_categs;

   // LOAD THE USERS NAME INTO THE USER FIELD
   $.post("get_logged_user.php", function(u_name) {
      $("#user").val(u_name);
   });

   // LOAD THE LIST OF JOBS INTO THE JOB LIST
   create_job_list();

   // CREATE THE TABLE OF EQUIPMENT
   create_equip_table();

   // RESET THE PAGE SO ALL FORM ITEMS ARE BLANK
   page_reset();

Comments really are one of the most powerful tools available to a programmer. When you’re first starting to program you should comment extensively…as you become familiar with the language you’re using and how the different blocks of your program are combined you may be able to scale back your commenting.

Leave a Comment

Your email address will not be published.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>