tk Style guideThe following set of tips are not specific to any language and apply to all code files.
If at all possible, break lines before they exceed 78 characters in length.
A special case of long lines is when elements are placed close together and
on the same line because whitespace is significant. (This occurs, for example,
when href attributes need to be calculated dynamically and
in place.) In theory, it is not always possible to break such a line up into
sufficiently short lines. Try to find innocent places inside tags where
newlines can be inserted, for example before, between or after
attribute-value pairs inside XML start tags.
<xsl:attribute name="href"><xsl:call-template name="getLinkURL"
/></xsl:attribute>
Indentation is made with spaces only. A tab character found somewhere in source can be replaced with spaces without hesitation.
Use two spaces for all ordinary indentation, both XML elements and XPath expressions.
<fields> <title type="string" /> <sort-order type="list"> <values> <ascending /> <descending /> </values> </sort-order> </fields>
Below are a few XML-related guidelines.
If a logical group of XML elements covers more than three non-blank lines of code, empty lines can be placed around the group to give it some breathing room.
<table class="presenter-list">
<tr>
<th colspan="2">
<xsl:value-of select="tk:property[ @name = 'title' ]" />
</th>
</tr>
<xsl:apply-templates select="tk:object[ @type = 'presenter' ]"
mode="list" />
</table>
Sometimes more visual clarity is achieved by keeping lines xsl:param elements close to their parent xsl:template start tag. Use your judgement in determining what looks best.
<xsl:template name="getLinkURL">
<xsl:param name="filename">true</xsl:param>
<xsl:call-template name="getURL">
<xsl:with-param name="filename" select="$filename" />
<xsl:with-param name="property" select="'document'" />
</xsl:call-template>
</xsl:template>
Use a space before the ending slash in empty elements. When writing groups of empty elements, each on a separate line, show that they belong together by aligning the ending slashes.
<values>
<always />
<html />
<protected />
</values>
Attributes can be placed on the same line with one space before each attribute-value pair.
When the combined length of all the attributes exceed the length of one
line, consider placing them vertically aligned one under the other. Put the
> immediately after the last attribute, or, in the case of an
empty element, put the /> after the last attribute with a space
in between. It is often a good idea to put a blank line after such a group of
attributes, if this helps separate different elements.
<form action="http://diporta.ibg.uu.se/run/authenticate"
accept-charset="ISO-8859-1"
method="post">
<input type="hidden" name="cmd" value="login" />
In other cases, however, keeping the elements together as a group takes
precedence. (In the below case, the subsequent elements don't really collide
with the attribute list, plus <br /> elements specifically
say something about, and thus belong together with, the elements that come
before them.)
<input type="password" name="password" size="10" maxlength="50" /> <br /> <br />
XPath expressions should be spacious rather than compact. Remember than whitespace is often ignored in many places within an XPath expression, and can therefore be used to highlight its structure. Even newlines are allowed.
Parentheses (()), brackets ([]) and braces
({}) often clutter up an expression, making it hard to read.
Insert spaces inside the parentheses when the expression inside would otherwise
be obscured by clutteriness. The idea here is to make the expression within
parentheses form a "visual pill", which stands out by itself. Inserting spaces
inside the parentheses help accomplish this.
<xsl:if test="tk:property[ @name = 'visibility' ] = 'always' or
tk:property[ @name = 'visibility' ] = $file-ending ">
Empty parentheses need no such spaces — they form a visual pill in themselves.
<xsl:with-param name="prefix"
select="concat( $prefix, position(), '.' )" />
Sometimes the insert-spaces-inside-parentheses rule should be broken in order to increase the "visual pill"-ness of a greater paranthesized expression in favor of a smaller one. Use your own good judgement and taste.
Do not place a space between a function name and its opening parenthesis.
When several similar XPath expressions follow on subsequent lines, it might make sense to align opening and closing brackets.
<edit>
<xsl:apply-templates select="tk:object[ @type = 'news' ]" />
<xsl:apply-templates select="tk:object[ @type = 'infotext' ]" />
<xsl:apply-templates select="tk:object[ @type = 'login-diporta' ]" />
</edit>
Sometimes in expressions which risk becoming too long, it is useful to break the line after the opening parenthesis or bracket, and to put the ending parenthesis or bracket on a separate line, in analogy with a block of code. In such a case, indent the expression inside relative to the closing parenthesis or bracket.
<xsl:value-of select="normalize-space( tk:property[ @name = 'title' ] )" />
Use whitespace around operators. That goes for arithmetic operators (like
+ or mod), comparison operators (like =
or >), and logic operators (like not and
and). If the same operator is repeated, see if it can be
vertically aligned to heighten the sense of repetition.
<xsl:when test="$target-type = 'menu' or
$target-type = 'layout' or
$target-type = 'document'">
Attempt to arrange parenthesized expressions in such a way that the position of the parentheses can be guessed from the way the lines are grouped together and indented.
<xsl:apply-templates select="
tk:object[ @type = 'ext-contact' or
( @type='reference' and
tk:property[
@name = 'target-type'
] = 'user' )
]" />