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.

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.