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 |
---|
|
<- Previous | Index | Next -> |
---|---|---|
RE: [xsl] standard method of docume, Bryan Rasmussen | Thread | Re: [xsl] standard method of docume, David Carlisle |
[xsl] xsk doubt [ ] vs ( ), william locksman | Date | Re: [xsl] xsk doubt [ ] vs ( ), Jeni Tennison |
Month |