As I see it, there are three major categories of program comments: descriptive, to-do, and comment-out. Programming languages should support native ways to differentiate these types of comments; none that I know of does and most don't have very many styles of comment at all.
Descriptive comments are the standard, and the ones everyone talks about. They include program “headstones” that describe what the program is supposed to do, inputs/outputs, log history of changes, etc.
/*
program: whatever
revision history:...
author:...
*/
...
//this function turns a 6-digit date string into a unix date
...
$foobar = $foo ^ 2 / $bar; //standard accounting forumula
To-Do comments are dropped into programs while you're working on – a “note to self” about something that needs to be fixed, or might be a problem later. I use php-style hash comments for these, but most languages don't support different styles of comments, so I do a standard comment followed by a hash (//#!error or REM #?values should be global, for example). I use #! for action items, things that are likely to crash if they aren't fixed, #? for things that probably should be fixed but probably won't cause a crash. Then before a program is released, I can look for #! that must be fixed, or #? that need attention. Finally, I also use to-do style comments for printing/hiding debug messages while I'm working on the code; before release these should be removed.
#!this will fail if we get more than 10 users
#!divide by zero error
#?will a salesman ever sell more than 10,000 items?
#?this code is ugly, could be refactored
#echo "$user : ".print_r($user, true);
Comment Out are comments that are applied to actual code, to disable it while leaving it in place. Sometimes this is to test different methods; sometimes it's no longer used but you're keeping it for reference; usually you're trying taking it out to see what it does. In PHP I use # for these, to differentiate them from descriptive // comments.
#old version
#$foobar = $foo ^ 2 / $bar; //standard accounting forumula
#new version, double the results
$foobar = 2 * ($foo ^ 2 / $bar) ; //standard accounting forumula
...
/* Removed: we no longer need user ID
$user_id = lookup($user_value);
if ($user_id = 0) {
$user_id = request_from_server($user_value);
}
*/
I tend to like descriptive comments to be lined up with the code, and todo/comment-out shifted to the left so I can see them when I'm looking through the code:
//loop through users, capitalize their names
foreach ($users as $user) {
#echo "$user : ".print_r($user, true);
$user->name = ucase($user->name);
#don't ucase user address
# $user->address = ucase($user->address);
#!user phone number needs to be parsed
}
Code editors that auto-indent code and langauges that are indent-dependent defeat this strategy.