To make the structure of a query more obvious, you should make appropriate use of whitespace and parentheses. Whitespace (line breaks, spaces, and tabs) is allowed anywhere between keywords to make it more readable.

It is helpful to split longer FLWOR and conditional expressions into multiple lines and indent each clause to line up, as shown in Example 15-1. FLWORs embedded within FLWORs should be further indented. When constructing XML results, you should indent the element constructors just as you would indent the elements in an XML document.

Less clear query
for $product in doc("catalog.xml")//product return
<product><number>{$product/number}</number>
<price>{for $price in doc("prices.xml")//prod
where $product/number = $price/@num
return $price/price}</price>
</product>
More clear query
for    $product in doc("catalog.xml")//product
return <product>
         <number>{$product/number}</number>
         <price>{for    $price in doc("prices.xml")//prod
                 return $price/price}</price>
       </product>

Parentheses can be used around most expressions to group them together. If the beginning and end of an expression are not obvious, parentheses are highly recommended. For example, a complex where clause in a FLWOR, or a complex then clause in a conditional expression, are much clearer when wrapped in parentheses.

Choosing meaningful names can also make a query much easier to understand. This includes the names of variables, functions, and function parameters. Names can also be used along with repeating let clauses to make an expression more clear. For example, in the expression:

let $substring := substring($myString,1,32)
let $substringNoQuotes := replace($substring,'"','')
let $substringUpperCase := upper-case($substringNoQuotes)
return $substringUpperCase

the names are bound to the string in various states of processing. This is more obvious than its equivalent:

upper-case(replace(substring($myString,1,32),'"',''))

Namespace prefixes should also be chosen carefully. When possible, use popular prefix conventions such as xs for XML Schema,wsdl for Web Services Description Language, and html for XHTML. If you are using several namespaces, assign prefixes to all of them rather than making one the default. This makes it more clear which namespace each name belongs to.

An important part of writing understandable queries is documenting them. Comments delimited by (: and :) can appear anywhere that insignificant whitespace is allowed in a query. For example, they may appear at the end of a line to explain the expression on that line, as a separate line, or as a block on multiple lines, as in:

 (:::::::::::::::::::::::::::::::::
  : The following expression returns the price of a product
  : It assumes there is one price per product element
  ::::::::::::::::::::::::::::::::::)

A standard method of documenting XQuery modules and functions is by using xqdoc tags. These tags, listed in Table 15-1, appear in normal XQuery comments. All of them are optional and most are allowed to repeat.

@author

@version

@since

@see

@param

@return

@deprecated

@error

Once a module is documented using xqdoc tags, human-readable HTML documentation can be generated automatically. The process is very similar to that of Javadoc, which generates documentation for Java classes. For more information, or to download the scripts to generate the documentation, see http://www.xqdoc.org.

Example 15-2 shows a function that is documented using xqdoc comments. The documentation, which appears before the function declaration, contains a textual description of the function, followed by the @param and @return tags to describe the inputs and output of the function. HTML tags (the b elements) are used in the description to enhance the display of the description in the resulting HTML documentation.

(:~
: The <b>functx:substring-after-last</b> function returns the part
: of <b>$string</b> that appears after the last occurrence of
: <b>$delim</b>. If <b>$string</b> does not contain
: <b>$delim</b>, the entire string is returned.
:
: @param $string the string to substring
: @param $delim the delimiter
: @return the substring
:)
declare function functx:substring-after-last
($string as xs:string?, $delim as xs:string) as xs:string?
 { ...  };