Documenting Equations in Programs and Spreadsheets

   We all have read somewhere that you can compute the basal area of a tree by:

Basal Area = .005454 * D²

where D is the DBH in inches, right? Well, quickly, can you tell me what value is used for PI in that equation? Please compute that before you read the rest of this article.

   In algebra class we were taught to "combine terms" whenever possible. This was to simplify the math when it was done by hand or with a slide rule. Done a lot of that lately in cruise compilation? Does it still make sense?

   I recently checked a computer program and found that the programmer was using a value for PI of 2.743 but nobody else had ever worked this nasty constant backwards to find that out. The programmer had no idea why that value for p was being used (but he offered to fix it – nice of him, don’t you think?).

   In the 60’s it made some sense to save computer time or storage by combining terms. These days writing computer code like that is like showing that you are really talented using a buttonhook – with the disadvantage of making the code mysterious.

   "Well", you say, "you could document the equation in the text of the computer program or with those neat little comments that pop up on some spreadsheets." Wrong. These are the last things that get corrected when a program or spreadsheet is fixed (if they ever get corrected).

   Don’t combine terms. It makes checking or correcting the work difficult, and there is no practical advantage to it. Did you compute the value of p that I asked for earlier in this article? Probably not. You have better things to do, right? Do I make my point? Therefore, these things never get checked.

   For the computation of basal area, you might put the following equation in the spreadsheet or program:

[ (DBH*1)*(1/12)*(1/2) ]² * 3.141504

   Most folks would recognize the computation of a circle with (Radius)(2)(PI). You could put in the notes that the 1 stands for 1 inch, the 1/12 converts to feet, the 1/2 from diameter to radius.

   Now if you use centimeters the 1/12 is changed to 1/100 to get basal area in square meters. To measure in centimeters, but get the area in square feet you could change (D*1) to (D/2.54) to convert centimeters to inches.

   If this equation bothers you, ask yourself why. If the wasted computer speed of multiplying by an extra 1 annoys you, you are living in the 60’s. If you just can’t stand having several constants instead of one, you are living back in the days you took algebra. If you like living in those times, remember that you are making life difficult for those that are not. If the value of PI bothers you because it is not quite correct, you still have not done the exercise from the beginning of this article.

   The difference with this kind of equation is that you know what is going on in this computation. In this day and age, that is increasingly important. Documentation matters, so make it readable and easy to change.