Developer Forums | About Us | Site Map
Search  
HOME > TUTORIALS > SERVER SIDE CODING > PERL TUTORIALS > ROAD TO BETTER PROGRAMMING: CHAPTER 2. COMMENTING YOUR CODE


Sponsors





Useful Lists

Web Host
site hosted by netplex

Online Manuals

Road to better programming: Chapter 2. Commenting your code
By Teodor Zlatanov - 2004-02-11 Page:  1 2 3 4 5 6 7 8

Commenting the beginning of the program

The program should begin with a brief explanation of its purpose. Don't make people scroll down several pages to figure out what you were doing. If you are using a version control system such as CVS, place the appropriate headers at the beginning of the file, such as the Id header. Be concise. Two lines, four at most, should be sufficient to describe a program briefly. Give a contact name, e-mail, telephone number, or team contact.

Listing 4
 
#!/usr/bin/perl -w 
# whodunit.pl: A script to solve a murder mystery 
# by joe@shmoe.com $Id: whodunit.pl,v 1.92 2000/08/08 19:08:50 joe Exp
$ 

The comment on the first line is a standard way on most UNIX systems to indicate which program runs when execution of the script occurs (everything after the '!' is considered the interpreter name). The -w flag signals to turn on warning -- always a good idea, even for an experienced programmer.

The second line (first comment line) is a brief description of the program and its purpose. The third line (second comment line) names the author, and gives an Id header that uniquely identifies the release date and version of the file. RCS and CVS specifically use the Id header, which updates automatically upon committing the script. For more on RCS and CVS, see Resources later in this article.



View Road to better programming: Chapter 2. Commenting your code Discussion

Page:  1 2 3 4 5 6 7 8 Next Page: Commenting initialization sections

First published by IBM developerWorks


Copyright 2004-2017 GrindingGears.com. All rights reserved.
Article copyright and all rights retained by the author.