Commenting Code - Tech Support Forums

Blazer06 · January 3rd, 2005, 05:45 PM

I want to be commenting code in line with standereds...

This is a typical page, and how I try to comment:

Code:

<!-- 700 Design -->
<!-- 2005-01-03 -->
<!-- support @ 700design.com -->
<!-- Blaise J Barstow -->

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<?

  //Sets what page to call from the server
  //If the page varible is not set, send them to the home page
  //Otherwise send them to whatever page they clicked to goto
  if($page==""){
    $page = "pages/home.php";
  }
  else{
    $page = $page . ".php";
  }

  //Checks if the page exsists, if not sends them to 404 page.
  if(is_file($page) != "true"){
    $page = "pages/404.php";
  }

  //The side links arrays;
  //The headers and number of links under that particular header
  $array_header = array("Main", "Listings", "Buyers", "Sellers", "Contact");
  $array_header_links = array(2, 4, 3, 3, 2);
 
  //Defines the link names, and actual links.
  $array_pages = array();
  $array_page_name = array();

  //Main Pages added to array
  $array_pages[] = "pages/home";
  $array_pages[] = "pages/titlefive";
  $array_page_name[] = "Home";
  $array_page_name[] = "Title Five";

  //Listing Pages added to array
  $array_pages[] = "pages/listings/house";
  $array_pages[] = "pages/listings/trailer";
  $array_pages[] = "pages/listings/land";
  $array_pages[] = "pages/listings/search";
  $array_page_name[] = "House Listings";
  $array_page_name[] = "Trailer Listings";
  $array_page_name[] = "Land Listings";
  $array_page_name[] = "Search Listings";

  //Buyers Pages added to array
  $array_pages[] = "pages/buyers/areainfo";
  $array_pages[] = "pages/buyers/resources";
  $array_pages[] = "pages/buyers/faq";
  $array_page_name[] = "Area Infomation";
  $array_page_name[] = "Resources";
  $array_page_name[] = "FAQ";

  //Sellers Pages added to array
  $array_pages[] = "pages/sellers/howtosell";
  $array_pages[] = "pages/sellers/resources";
  $array_pages[] = "pages/sellers/faq";
  $array_page_name[] = "How To Sell";
  $array_page_name[] = "Resources";
  $array_page_name[] = "FAQ";

  //Contact Pages added to array
  $array_pages[] = "pages/contact";
  $array_pages[] = "pages/webmaster";
  $array_page_name[] = "Contact Us";
  $array_page_name[] = "Webmaster";

  //Total number of pages
  $array_pages_count = count($array_pages);

  //The counter varible for the page that needs to be appended
  $find_current_page = 0;

  //Makes each page a link.
  while($find_current_page < $array_pages_count){
    $page_match = $array_pages[$find_current_page] . ".php";

    //If they are on the selected page, the page is set to be a special link (has lines above and below it)
    if($page_match == $page){
      $array_pages[$find_current_page] = "<p class='thispage'><a href='index.php?page=$array_pages[$find_current_page]'>$array_page_name[$find_current_page]</a></p>";
    }
    //Regular links made here:
    else{
      $array_pages[$find_current_page] = "<a href='index.php?page=$array_pages[$find_current_page]'>$array_page_name[$find_current_page]</a>";
    }
    $find_current_page++;
  }

?>

<!-- Start HTML Document -->
<html>

  <!-- Head (Javascript would go here) -->
  <head>
    <meta http-equiv='Content-Type' content='text/html; charset=ISO-8859-1' />
    <!-- Style Sheet Reference Link -->
    <link rel='stylesheet' type='text/css' href='styles/css.css' />

    <!-- Title displayed in the browser window -->
    <title>
      Bartlett Real Estate
    </title>

  <!-- End Head (use no more javascript) -->
  </head>

  <!-- Start Body part of the page. (Content) -->
  <body>
    <!-- The Main Container -->
    <div id='container'>

      <!-- Area for the banner to be displayed -->
      <div id='banner'>
        <img src='img/logo temp.png' alt='Bartlett Real Estate' />
      </div>

      <!-- Area for the header to be displayed -->
      <div id='header'>
        Header Info Goes Here!
      </div>

      <!-- The links bar (left sidebar) -->
      <div id='links'>

        <!-- CODE BELOW GENERATED BY PHP -->

        <?
          //The counter to find which page to add
          $find_page = 0;
 
          //The counter to find which header to display       
          $find_header = 0;

          //The total number of headers
          $count_header = count($array_header);

          //For each one of the headers, adds the appropriate links and header to the page
          while($find_header < $count_header){
            echo("<h1>$array_header[$find_header]</h1>");

            //Sets the counter to find the actuall link to display
            $find_link = 0;
            while($find_link < $array_header_links[$find_header]) { 
              //Echos the link to the page
              echo("$array_pages[$find_page]");

              $find_link++;
              $find_page++;
            }  

            $find_header++;
          }

        ?>

        <!-- END LINKS GENERATION -->

        <h1>Accessibility</h1>
          <a href='http://jigsaw.w3.org/css-validator/validator?uri=http://www.rbre.net'>
            <img style='border:0;width:88px;height:31px' src='http://jigsaw.w3.org/css-validator/images/vcss' alt='Valid CSS!' />
          </a>
          <a href="http://validator.w3.org/check?uri=referer">
            <img src="http://www.w3.org/Icons/valid-xhtml11" alt="Valid XHTML 1.1!" height="31" width="88" />
          </a>
      <!-- End Links Bar -->
      </div>

      <div id='content'>
        BLAH!
      </div>

      <div id='footer'>
        © 2004 - Bartlett Real Estate <br />
        Site Design by: <a href='http://www.700design.com'>700 Design</a>
      </div>

    <!-- End Main Container -->
    </div>
  <!-- End Body part of the page. (Content) -->
  </body>

<!-- End HTML Document -->
</html>

How does the commenting look? What areas should i expand upon / etc.?

Blaze

James T · January 3rd, 2005, 06:17 PM

Good to see. I know I have trouble reading even my own programs. I think the accepted time that this happens is about 6 weeks ... not long.

I think you should try to avoid repetition of your code in comments. There should be an underlying assumption 1/ that the person reading it has a basic understanding of how to code in the first place (otherwise generic *go away* comment is useful

). So you shouldn't precurse an if then else construct with an if then else comment.

I note some of your variable names and directory names are really good and in many instances do your commenting for you. This is very good.

A real issue is, if you put in to many comments then the work load to maintain the comments up to date becomes as large as the upkeep of the code itself. At some point you'll just do the code and not bother with the comment, at which point you create a real problem and almost make it worse than not having a comment at all.

A really good pointer on this stuff is Eric Raymond's The art of unix programming here at http://www.faqs.org/docs/artu/ .

**Socalgal** · January 5th, 2005, 11:38 AM

You need not tag each line, but only need your tagging at the beginning and end of your comment, like so:

Code:

<!-- You need not tag each line, 
but only need your tagging at the beginning and end of your comment, 
like so-->

/*You need not tag each line, 
but only need your tagging at the beginning and end of your comment, 
like so*/