Coding Standards: The Ugly Duckling of Web Development

---

By Brett Goodwin

Friday, December 15th, 2006 at 4:30pm

A few weeks ago a document came across my desk, which at first glance caused me to grimace with distaste. It was a department-wide memo to our Professional Services team reminding us of Best Practices procedures for writing XSLT code. Anyone who has experience with programming has inevitably had that one professor or supervisor who insisted that you comment every single line of code and organize your code sections as though he were going to print out the finished source, frame it, and stick it on the wall. Most people know on some level what they are supposed to do to maintain their code’s readability, but very often it gets ignored. In fact among some programmers there is a kind of perverse pride in being able to write functions so complex and obscure that no one could ever decipher them. And sometimes this is seen as a kind of job security, if your employer is dependent on you to maintain the rat’s nest, which supports the entire corporate infrastructure.

Nevertheless, on further reflection I decided that it might not be a bad idea to make an effort to keep my code in line with our established best practices. It is, after all, a show of courtesy towards my coworkers, and would help cut back on the number of people coming by my desk to ask me about things I had written. And as much as we like to think that we have the capacity to interpret everything we’ve written at a later date, sometimes reviewing things that I’ve coded as little as two weeks ago can require 15 minutes spent refreshing my memory.

That being said, I’d like to go over some best practices that we’ve been putting to use here at Hannon Hill in the development of our XSLT stylesheets. Ignore them at the risk of your own frustration.

• First, and most obvious, indent (and do it with tabs, not spaces).  The standard practice is to add one tab of indent for each enclosing tag.  For example:
  
  <xsl:stylesheet>
        <xsl:template match="/system-index-block">
             <h1>xsl:value-of select="heading"/></h1>
             <p><xsl:value-of select="paragraph"/></h1>
        </xsl:template>    
  
  

• Comment your code liberally. If you feel like you’re putting in too many comments, it’s probably just enough. Specifically, be sure to give explanations of the purpose of any variables you use, and the function of each template.
  
  
• Try to keep your XPath statements simple. These are the statements that appear with select=”…” sections. When these statements get too long they can be very hard to decipher, so it’s best to simplify as much as possible.
  
  

These are just a few of the most significant rules, but there are many other things you can do to improve your code’s readability. You will develop your own style as you become more proficient in XSL, but hopefully it will be one that won’t cause future generations of developers any grief. Just remember the golden rule: “submit code unto others as you would have them submit code unto you.”

Category

• Commentary