## Monday, November 14, 2011

### Leaving comments in real life

As a programmer I like to write comments because I know that some future person (often me) is going to need to know something about my code that won't be immediately obvious from reading it. Here's a recent example from my homebrew display's code:
// protocol_init: Set up a newly powered-on string of lights.  The lights are arranged
// in an array wired diagonally starting from the bottom left.  For ease of programming
// it's better if they are given numbers which correspond to coordinates.  Given that
// each LED has a 6 bit address it's possible to address the entire array using 3 bits
// for X and 3 bits for Y (the 50th LED will be (7,0) and the display itself will be
// numbered starting (0,0) up to (6,6).
//
// For example, the first (single LED) diagonal is (0,0), the second diagonal is (1,0) and
// (0,1), the third is (2,0), (1,1) and (0,2)... the loop inside this function expolits this
// to program the LEDs.
//
// The actual display is wired as follows
//
// 21 33 34 42 43 47 48
// 20 22 32 35 41 44 46
// 10 19 23 31 36 40 45
// 09 11 18 24 30 37 39
// 03 08 12 17 25 29 38
// 02 04 07 13 16 26 28
// 00 01 05 06 14 15 27
//
// The initializer sets these up with the following addresses (corresponding to X in the bottom
// 3 bits and Y in the top 3 bits)
//
// 06 14 22 30 36 46 54
// 05 13 21 29 37 45 53
// 04 12 20 28 36 44 52
// 03 11 19 27 35 43 51
// 02 10 18 26 34 42 50
// 01 09 17 25 33 41 49
// 00 08 16 24 32 40 48
//
// Thus the order in which the (x, y) coordinates are programmed is:
//
// (0, 0), (0, 1), (1, 0), (2, 0), (1, 1), (0, 2), (0, 3), ...
//
// Also notice that the sum of the coorindates in each diagonal is related to the direction
// of wiring: even diagonals are wired upwards, odd diagonals downward.
//
// Initially all the LEDs are set to RGB color (0,0,0) with no brightness (i.e. they are
// each sent an address and told to be off).
void protocol_init()
{
pinMode( DISPLAY_PIN, OUTPUT );
digitalWrite( DISPLAY_PIN, LOW );

// This is done so we see that the bus is low before we do anything on it

delay( 1000 );

// See comment preceding this function for explanation of this loop

for ( int sum = 0; sum <= 12; ++sum ) {
if ( ( sum % 2 ) == 0  ) {
int x = (sum < 8)?0:(sum-6);
for ( int y = sum - x; y >= 0; --y, ++x ) {
if ( x < 7 ) {
init_led( x, y );
}
}
} else {
int x = sum;
for ( int y = 0; ( y < 7 ) && ( x >= 0 ); ++y, --x ) {
if ( x < 7 ) {
init_led( x, y );
}
}
}
}
}

This works well in code, but I've found it also works well in real life. Whenever you spend any time debugging something, or figuring out how something works, leave a note. Leave a physical note. You'll appreciate it years later when you discover you've documented your home wiring, plumbing, plants in the garden, etc.

In one of my old apartments any person who opens up the cable TV wiring will find little notes attached to the cabling using paper luggage tags. The notes detail which cables link to which boxes in the apartment, and why they are connected or not.

I've done something similar with plumbing (especially leaving notes about which stopcocks isolate different parts of the plumbing system) and low-voltage lighting. It's also useful to leave yourself (and future home owners) notes about things that are useful to know (for example, when a particular piece of equipment was last serviced). There's a note attached to the water filter of my washing machine with the last date I cleaned it.

I do this because (a) I'll never remember the details of plumbing, electrics, etc and (b) there's nothing like a note left close to the thing you're investigating.

One day, I suppose, it'll be possible to use an app-for-that, to leave virtual notes. But until then, and perhaps afterwards, there's nothing like a little hand-written note or diagram on paper.

Labels:

If you enjoyed this blog post, you might enjoy my travel book for people interested in science and technology: The Geek Atlas. Signed copies of The Geek Atlas are available.

<$BlogCommentBody$>

<$BlogCommentDateTime$> <$BlogCommentDeleteIcon$>

<$BlogBacklinkControl$> <$BlogBacklinkTitle$> <$BlogBacklinkDeleteIcon$>
<$BlogBacklinkSnippet$>