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.

 
#!/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.