[xsl] Some things I learned about writing code

["Roger L Costello costello@xxxxxxxxx" <xsl-list-service@xxxxxxxxxxxxxxxxxxxxxx>]

  1.  When writing code, I need to focus very intently. A momentary loss of
focus often results in introducing erroneous code.
  2.  There is input data that code consumes and output data that code
produces. What is the format of the input data? What is the format of the
output data? I like using a format that has a good query language. That way I
can run queries on the input data to check that I correctly understand the
input data and I can run queries on the output data to check that my code
generated the correct output data. I really like the XPath query language - it
is both simple and powerful. Of course, XPath is only applicable to
XML-formatted data, so I like formatting the input and output data as XML.
  3.  I have found that most of the errors in my code falls into these three
buckets:
     *   Logic problems
Example: Recently I wrote a function to recursively process a list. Normally
in a recursive function when the list is empty the right thing to do is to
immediately return. And that's what I did. However, as I reviewed my program's
output (it was a huge output) I noticed that the output was missing the final
record (from the last list item). I scratched my head and wondered, "The
program is correctly outputting thousands of records, why would it decide to
omit the final record?" Turns out, the recursive function should not
immediately return when the list is empty. Instead, it should output the final
record. I had made a logic error.
     *   Incorrect/incomplete understanding of the input data
Example: I have input data that someone created, and they weren't consistent
in how they named their header fields. Most of the headers ended with
'Records' but some ended with 'Record'. So, I wrote a program that
"normalized" all the headers, i.e., the program made sure that every header
ended with 'Records'. Purely by accident, I discovered one header that didn't
end with either 'Records' or 'Record'. Luckily, I caught this and made the
correct adjustment to my program. I had an incorrect/incomplete understanding
of the input data.
     *   Dependencies
Example: My input file contained (among other things) strings representing the
names of figures: Figure 5-1 Blah blah, Figure 5-2 Boo boo, and so forth. When
each such string was encountered, my program would input the appropriate image
file. My program was written as a choice: If the string starts with "Figure
5-1" then input ABC.png, else if the string starts with "Figure 5-2" then
input DEF.png, and so forth. Turns out, there were 10 figures in the input, so
my choice statement had this at the end: ... else if the string starts with
"Figure 5-10" then input XYZ.png. I noticed that when I ran my program,
instead of getting the XYZ.png image (for Figure 5-10) I always got the
ABC.png image. After scratching my head for a while, I realized that the
string "Figure 5-10" matches: if the string starts with "Figure 5-1". I had to
place the test for "Figure 5-10" before the test for "Figure 5-1". I hadn't
recognized a dependency.
  4.  If the input data is small, then I can manually process it, i.e., no
need to write code. But what is "small"? It is shocking how quickly the size
of the input data becomes overwhelming to me; more than a dozen records and I
start making tons of mistakes. Unless the data is extremely small (say, less
than a dozen records), I need to write a program to process the data.
  5.  Not only do I make mistakes in manually processing input data that is
even a little bit large, I make mistakes in manually writing code that is even
a little bit large. So I try, as much as possible, to write code that writes
code.
  6.  Input data is in a certain form. Sometimes that form is complicated. It
doesn't take much complicatedness before it overwhelms my brain, so I like
using a programming language that allows me to express this to the programming
language's processer: "Hey processor, whatever form the input data is in,
proceed through its items from top to bottom; here's a set of "rules" (code)
for each item. When you get to an item, execute the rule that is appropriate
for that item." I like that because it relieves me from having to keep the
structure of the input in my brain. I really like the XSLT programming
language because it allows this; it allows me to write a set of rules and then
the XSLT processor figures out which rule to process at which time.
Those are some things that I've personally learned. What are some things that
you've learned?
/Roger