Comments are critical for making computer programs readable by humans. Intelligent programmers do their best to make the code self-documenting, by using descriptive variable names and writing non-cryptic code instead of showing off their cleverness. Self-documenting code requires far fewer comments.

# Self-documenting Bourne shell code written by a wise programmer
printf "Please enter your name: "
read name
if [ $name = "Bob" ]; then
    printf "Hi, Bob."
fi

# Cryptic code intended to show off how clever I am, or just to avoid
# typing because I'm lazy and short-sighted
read n; test $n = "Bob" && printf "Hi, Bob."
            

Regardless how well-written a program is, some comments will be needed. Keep in mind that a computer program is a way to explain something to a computer, which requires a different approach and far more detail than human beings are used to dealing with. Hence, it's impossible to make the code itself completely self-documenting. Comments are a supplement to help humans understand a set of instructions aimed at a machine.

In ANSI C and C++, a comment is everything from a // to the end of the line, or everything between /* and */, even if it spans lines.

In Fortran 90 and later, a comment is everything from a '!' character to the end of the line.

Well-written programs are typically around 1/3 comments, 2/3 code, but this varies widely depending on the complexity of the program. Simple programs may require fewer comments, and complex programs may require more comments than code. Blank lines are a form of comment as well. Separating logical blocks of code, each of which performs a different function, helps document the structure of the program.

Good comments build good karma. You will be happy with yourself later, after your short-term memory about the code you are writing has faded, if there are comments that help you remember how it works. Others who did not write the code, but have to work on it, will also be happy with you.

Line comments document one to a few lines of code, and may appear above the code or to the right of it. If above the code, they should not be separated from the code they document with a blank line, but should be separated from the code above. If next to the code, they should be indented consistently with other nearby line comments to make the code easy to read.

double  radius,     // Radius of the circle
        area;       // Area of the circle

// Input the radius
printf("What is the radius of the circle? ");
scanf("%lf", &radius);

use ISO_FORTRAN_ENV     ! Enable INPUT_UNIT, OUTPUT_UNIT, ERROR_UNIT, etc.

! Disable implicit definitions (i-n rule)
implicit none
            

Block comments are multi-line comments that document a section of code, such as a whole subprogram, a loop, or just a block of code that does a particular task. They are formatted nicely and consistently so that they stand out, and are separated from the other code by blank lines above and below.

/*
 *  Description:
 *      Compute the area of a circle given the radius as input.
 */
            

!-----------------------------------------------------------------------
!   Description:
!       Compute the area of a circle given the radius as input.
!-----------------------------------------------------------------------