Progress to Acquire MarkLogic - Learn More
BLOG ARTICLE

XQuery Coding Guidelines

Back to blog
06.29.2011
2 minute read
Back to blog
06.29.2011
2 minute read

Code gets read more often than it gets written, so how it gets laid out on the screen is a critical component of maintainability. When a project involves more than one person checking in code, it gets even more important.

So, here’s a peek inside the MarkLogic Engineering team’s process — our set of agreed-upon guidelines for formatting XQuery code. It’s arranged in a laws-of-robotics sequence with the cardinal rule first. Following rules fill out the details, but can’t override the earlier rules.

It’s my hope that this is a useful resource for XQuery programmers everywhere.  The intent of this guide is to provide a few key rules for sensible application, rather than exhaustive enumeration.

Rule 0

Thou shalt not mix tabs and spaces. The entire project must exclusively use spaces (four) for indentation, except for third party libraries (e.g. XSLTforms, YUI).

Rule 1

Structure function signatures using the following example:

declare function my:function(
    $a as xs:string,
    $b as element(my:options)
) as empty-sequence()
{
    (: body of function :)
};

Rule 2

Use common sense and make code readable on the screen unless it would conflict with rule 0 or 1.

Rule 3

If editing existing code, adopt a style to fit in with what’s already there, unless it would conflict with rules 0, 1 or 2.

Rule 4

If/Then/Else or For/Let/Where/Order by/Return statements should either fit on a single line, or else have the aforementioned keywords left aligned, unless it would conflict with rules 0, 1, 2 or 3.

Examples:

(: one line if/then/else :)
if ($condition) then $action else ()
(: multiple line if/then/else :)
if ($condition)
then xdmp:log("If we kept this on one line, it would be unreadable")
else xdmp:log("This is a very long action, don't want it to scroll")
(: chained if/then/else :)
if ($condition)
then xdmp:log("If we kept this on one line, it would be unreadable")
else

    if ($condition2)
    then xdmp:log("This is a very long action, don't want it to scroll")
    else
        for $i in (1,2,3)
        return concat("line ",$i)
(: flwor :)
let $a := "alpha"
for $i in (1 to 50)
where $i mod 2 eq 1
return concat($a,$i)
(: flwor :)
let $a := "alpha"
for $i in (1 to 50)
let $x := $i mod 2
where $x eq 1
return concat($a,$i)
(: flowr with subordinate flwor :)
let $a := "alpha"
let $x :=
    for $i in (1 to 50)
    where $i mod 2 eq 1
    return concat($a,$i)
return $x

Rule 5

Use a consistent amount of indentation as the rest of the project (four spaces), unless it would conflict with rules 0, 1, 2, 3 or 4.

Rule 6

Use sparing comments to indicate the intent of blocks of code; if the project uses XQDoc-style comments, do this also, unless it would conflict with rules 0, 1, 2, 3, 4 or 5.

Rule 7

Use short, but meaningful, variable and function names. Use a default prefix instead of fn: and always use a prefix for defined functions, unless it would conflict with rules 0, 1, 2, 3, 4, 5 or 6.

Micah Dubinko

Read more by this author

Share this article

Read More

Related Posts

Like what you just read, here are a few more articles for you to check out or you can visit our blog overview page to see more.

Tutorial

Poker Fun with XQuery

In this post, we dive into building a full five-card draw poker game with a configurable number of players. Written in XQuery 1.0, along with MarkLogic extensions to the language, this game provides examples of some great programming capabilities, including usage of maps, recursions, random numbers, and side effects. Hopefully, we will show those new to XQuery a look at the language that they may not get to see in other tutorials or examples.

All Blog Articles
Tutorial

Protecting passwords in ml-gradle projects

If you are getting involved in a project using ml-gradle, this tip should come in handy if you are not allowed to put passwords (especially the admin password!) in plain text. Without this restriction, you may have multiple passwords in your gradle.properties file if there are multiple MarkLogic users that you need to configure. Instead of storing these passwords in gradle.properties, you can retrieve them from a location where they’re encrypted using a Gradle credentials plugin.

All Blog Articles
Tutorial

Getting Started with Apache Nifi: Migrating from Relational to MarkLogic

Apache NiFi introduces a code-free approach of migrating content directly from a relational database system into MarkLogic. Here we walk you through getting started with migrating data from a relational database into MarkLogic

All Blog Articles

Sign up for a Demo

Don’t waste time stitching together components. MarkLogic combines the power of a multi-model database, search, and semantic AI technology in a single platform with mastering, metadata management, government-grade security and more.

Request a Demo