Pretty sad that all these examples are bad comments not good ones.

Here's a comment from some code that I posted to my blog. The idea was that this would explain in detail to someone reading the code what I was doing with the pieces of a wooden train set. This was critical to the operation of the program and I imagined that many of the readers of the code would need a careful explanation.

It turns out that I'd forgotten what this code does so the comment was helpful.

  # The 15 possible pieces: a straight edge (which has $unit length) and
  # is used as the measurement for everything else, a bridge (which is
  # twice the length of the straight edge; it is actually supplied in
  # two pieces but for the purposes of this program is considered to be
  # a single piece) and a curve (using $radians_in_curve above the
  # length of the straight line between the ends of the curve is
  # calculated).
  #
  # Each entry consists of three parts:  
  #
  # length: the length in a straight line between the ends of the piece
  # at its centre. 
  #
  # angle: the angle (in radians) between the straight line through the
  # piece and a tangent to the curve at the piece's start.  This only
  # applies to curved pieces where the straight line is the line joining
  # its two endpoints.
  #
  # count: how many of these pieces are supplied.
  #
  # Note that curves can be placed in either a clockwise or
  # anticlockwise direction. The program detects this by looking at the
  # angle.  If it's non-zero then the piece has two orientations.

  my %pieces = (
    Bridge   => { length => $unit * 2,
                  angle  => 0,
                  count  => 1 },

    Straight => { length => $unit,
                  angle  => 0,
                  count  => 2 },

    # Here's a curved piece, the angle a is $radians_in_curve, the
    # length l of a side is $unit.  So length is the distance between
    # the points labelled s and f. Bisect the angle a you get a right
    # angle triangle with hypotenuse of length $unit and angle at the
    # vertex of $radians_in_curve/2.  So the angle b is $PI/2 -
    # $radians_in_curve/2. By simple trigonometry the length is twice
    # $unit * cos($PI/2-$radians_in_curve/2).
    #
    #                  s
    #                  C
    #               .  .  C
    #             .   b    C
    #         l .       .   C
    #         .              C
    #       .            .   C
    #     .  a               C
    #   .  .  .  .  .  .  . C
    #  o                    f
    #
    # To calculate the angle to the tangent at point s (the angle c),
    # note that the angle formed by os and the tangent is a right angle
    # (since os comes from the centre of the circle).  So b+c is $PI/2
    # but b is $PI/2 - $radians_in_curve/2 and so c is
    # $radians_in_curve/2
    #
    #                  s
    #                  .
    #               .  .  .
    #             .   b  c  .
    #         l .       .     .
    #         .                 .
    #       .            .        .
    #     .  a                      .
    #   .  .  .  .  .  .  .  .  .  .  .
    #  o                    f
    #

    Curve    => { length => 2 * $unit * cos($PI/2-$radians_in_curve/2),
                  angle  => $radians_in_curve/2,
                  count  => 16 }
  );

http://blog.jgc.org/2010/01/more-fun-with-toys-ikea-lillabo-...

Interestingly, the first line of this comment contains an error. There are 19 pieces not 15.