Re: [xsl] Annoying XSLT code

[JBryant@xxxxxxxxx]

> I agree that sometimes this can be overused and that tracking
> variable declarations across miles of files is no fun, but I
> also agree with David that it's a useful technique that can
> contribute to good code. A balance must be struck. Documenting
> your code (with comments if necessary) can also help the
> general problem of code opacity.

A useful "house rule": If you use anything from an imported stylesheet, 
add a comment at the point where it is first used in the current 
stylesheet that indicates the name of the stylesheet where it originated.

Some problems definitely lend themselves to being solved with multiple 
stylesheets. In those cases, I like to have a master stylesheet that lays 
out the whole solution and indicates which stylesheet implements which 
part of the solution. Then I add comments to the top of each stylesheet 
that identify the master and define what this particular stylesheet does.

I also write readme files and check them into source control, so that each 
stylesheet I write has at least minimal documentation somewhere in the 
same directory. I recently had to hand over one of our document production 
systems to a customer, and they were happy to see some documentation 
bundled with the source code. Even if it's not what I would call extensive 
documentation, they liked it better than what they usually get, which is 
nothing.

I bet that, between us all, we could whip up a set of guidelines that 
would make a good set of XSLT coding conventions. It's mostly going to 
come down to don't obfuscate your code and do something to document 
(comments mostly) your code, but the specific ideas might be useful to 
see.

Jay Bryant
Bryant Communication Systems
(presently consulting at Synergistic Solution Technologies)