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 regular code

Commenting regular code is pretty easy. Just line up the comments when possible, be concise, and don't be afraid to explain things in-depth when they are unclear.

Listing 9


print Dumper \%ENV;                     # print the full ENV hash

# get the environment variable names that begin with USER
@user_vars = grep(/^USER/, keys %ENV); 

# print the values in all the variables that begin with USER, using a
# hash slice
print Dumper @ENV{@user_vars};          

print "Done\n";                         # print "done" message

# TODO: find better method of sorting variables
# TODO: use Data::Dumper with variable names

Note that comments begin either at column 0 or column 40. Consistency makes comments more readable. Also, multi-line comments are fine when necessary. You can also use comments to note where functionality is missing, buggy, or incomplete. The "TODO" word is helpful in case you want to look through all your code and see what things are still incomplete -- a quick grep command will print out all the TODO items.

There's no need to comment every single line of code, but keep in mind that comments are the single best resource when debugging or extending programs. Any other source of programmer documentation is likely to be one step behind the actual code, unless the programmer has been very diligent.



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

Page:  1 2 3 4 5 6 7 8 Next Page: Commenting loops and conditionals

First published by IBM developerWorks


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