## 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.

Morgan Delaney said...

That's so true. I have an in-store credit for Visions that isn't valid for 4 years. I left myself a "comment" on the TV and I haven't forgotten about it yet!

Anonymous said...

Good plan!

I used this method in text-books whilst learning, often cataloging important parts with Post-It Notes inserted in specific area with annotations written on - easy to refind.

I would, however, caution against the App-for-that approach. Paper doesn't break, or get migrated to a new system which is incompatible with the previous.

S.

yakshaving said...

Isn't that like StickyBits?

rog peppe said...

I hope you write the plumbing comments using a waterproof medium!

Siberiano said...

Reminded me of photographing my apartment during the reconstruction. I have concrete floor with tubes for cables in it, and canals for cables in the walls made with hammer drill. They all are hidden and impossible to detect even with special device. But thanks to photos I know where I can drill safely.

Actually, I discovered this only after the repairs were done. At that moment I naively thought it is easy to memorize this. :)

metrofx said...