4 ms·
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 expla
by jgrahamc 13y ago
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-train.html 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.
- eitally 13y agoThat's beautiful! I have lately been encouraging all my team to take advantages of comments to document the high level business logic as it was at the time of development. It provides utility during code review and future dev, and it's a terrific CYA when debating with stakeholders about what they said they wanted then versus what they "remember" asking for.
- jgrahamc 13y agoThat example is particularly verbose because I knew I'd forget it and it wasn't obvious what I was doing. A clear example of something shorter is: // Briefly the algorithm goes like this: // // Slide a 16x16 block across the entire image from left hand corner // to bottom right hand corner. For each 16x16 block perform a // discrete cosine transform on it and then quantize the 16x16 block // using an expanded version of the standard JPEG quantization matrix. // // Each quantized DCT transformed is stored in a matrix with one row // per (x,y) position in the original image (the (x,y) being the upper // left hand corner of the 16x16 block being examined. // // The resulting matrix is lexicographically sorted and then rows that // match in the matrix are identified. For each pair of matching rows // (x1,y1) and (x2,y2) the shift vector (x1-x2,y1-y2) (normalized by // swapping if necessary so that the first value is +ve) is computed // and for each shift vector a count is kept of the number of times it // is seen. // // Finally the shift vectors with a count > some threshold are // examined, the corresponding pair of positions in the image are // found and the 16x16 blocks they represent are highlighted. // // Uses the FreeImage library (http://freeimage.sf.net/) to access // image data From: http://blog.jgc.org/2008/02/tonight-im-going-to-write-myself-aston.html http://blog.jgc.org/2008/02/tonight-im-going-to-write-myself...
- dspillett 13y ago> as it was at the time of development Also as it was interpreted at the time of development - the two should be the same of course but we don't live in a perfect world. If a comment explains exactly what the code is trying to do and why, and the "what" matches the code but doesn't match the client expectations then as well as fixing the code you know you might need to update documentation elsewhere too to make it cleare.