## Documenting Equations in Programs and SpreadsheetsWe 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 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 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
For the computation of basal area, you might put the following equation in the spreadsheet or program: [ (DBH*1)*(1/12)*(1/2) ] 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
Documentation
matters, so make it readable and easy to change. |

*Originally published January 1999*