Re: [xsl] standard method of documenting XSLT code?

Subject: Re: [xsl] standard method of documenting XSLT code?
From: Jeni Tennison <jeni@xxxxxxxxxxxxxxxx>
Date: Thu, 25 Apr 2002 10:51:47 +0100
Bryan Rasmussen wrote:
> Anyone out there have opinions on what things are the most necessary
> to comment in a stylesheet, and what things can best be left out.

I agree about basic template-level comments being more useful than
code-level comments.

The main comments that I find helpful are those concerning the
assumptions that have been made in the stylesheet about the structure
of the source document. For example, if you have an xsl:choose like:

  <xsl:choose>
    <xsl:when test=". = 'value1'">
      ...
    </xsl:when>
    <xsl:when test=". = 'value2'">
      ...
    </xsl:when>
  </xsl:choose>

then it's helpful to know whether value1 and value2 are the only
possible values, or if there are other possibilities that are
(correctly) being ignored. Or if you have a plain xsl:apply-templates,
with no select attribute, it's helpful to know what kinds of nodes
you're assuming will be processed by that instruction (just
descriptors like "inline elements" rather than listing them all). Or a
comment that indicates the expected type of a parameter. These kinds
of comments make following the flow of the stylesheet easier, and they
help identify areas that might need to change when/if the source
markup language changes.

Other comments that I think can be helpful are those that explain
complex XPath expressions in plain language. So things like:

  <!-- $rows holds a node set of unique row elements, by their code
       attribute -->
  <xsl:variable name="rows"
    select="//row[count(.|key('rows', @code)[1]) = 1]" />

XPath 2.0 allows comments *within* expressions (using the syntax {--
... --}), which would mean you could do:

  <xsl:variable name="rows"
    select="//row[count(.|key('rows', @code)[1]) = 1]
            {-- select unique row elements by their code attribute --}" />

You can see why this might be necessary, given that XPath expressions
will contain for and if statements...

The other thing to mention is that you can go quite a long way towards
making a stylesheet more readable and understandable without adding
comments all over the place, just by using helpful variable names, key
names, mode names, template names and so on.

Cheers,

Jeni

(P.S. I wrote an article about documentation for the "XPath & XSLT on
the Edge unlimited edition" website
(http://www.unlimited-edition.com/), but it doesn't seem to have
appeared yet...)

---
Jeni Tennison
http://www.jenitennison.com/


 XSL-List info and archive:  http://www.mulberrytech.com/xsl/xsl-list


Current Thread