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 (4) for indentation, except for third party libraries (e.g. XSLTforms, YUI).

Rule 1

Structure function signatures using the following example:

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:

 

Rule 5

Use a consistent amount of indentation as the rest of the project (4 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.