The reasoning behind this one is similar to why descriptive variable names are important. However, in this case, the comment should be a short description of the underlying meaning or intent of the statements to which it refers. For instance, a comment like this is useless:
C-- Add one to NUMBARS NUMBARS = NUMBARS+1
Whereas this one helps remind us what NUMBARS is for:
C-- Count this bar of gold in the total NUMBARS = NUMBARS+1
While the first comment is technically correct, its usefulness to another programmer is nil because it just repeats the FORTRAN statement in English. You'll notice that I used ``C--'' to start the comment instead of just ``C''. This helps your eye pick out the comments in your program at a glance. This is another "trick" that makes comments more useful to someone besides the author of the original program.
There is debate about whether or not there can be ``too much'' commenting in a program. I doubt that anyone in this class is going to suffer from this problem, but I thought I would mention it. There is such a thing as having too many comments. My rule of thumb that I use is to put a comment on each group of related statements, such as a bunch of PRINT statements displaying a menu and a READ statement that puts the user's menu choice into a variable. One comment for the group is sufficient; one needn't put a comment for every statement in the program.
If an algorithm or method involves some computational ``trick'' or ``shortcut'', then perhaps a paragraph at the top of the relevant block explaining the method is in order. If the block of code is based on some mathematical proof unique to the particular problem, it might even be appropriate to include the proof in the comment block. For standard algorithms that are elaborate or tricky, a reference to a paper or book describing the algorithm's functioning is a good idea. The algorithms you encounter in this course aren't likely to fall into this more complex category.
Another rule of thumb is to place a short paragraph describing the purpose of each SUBROUTINE, FUNCTION or PROGRAM module just before the corresponding SUBROUTINE, FUNCTION or PROGRAM statement. These needn't be essays describing all the details, just a broad overview or outline of the relevant module's purpose. Sometimes you can realize early on that you don't need a SUBROUTINE or FUNCTION after you've written the description of it. (Did you ever realize the answer to your question once you asked it aloud? Same thing.)
Hamlet Project