Xatapult's XML Blog

08/01/2010

XML Coding Standards

Filed under: General,Opinion,Standards and guidelines — xatapult @ 10:03
Tags: ,

Looking at the XML that is around, everybody seems to use different standards for element and attribute names. Some people write their elements in all uppercase, like <USERNAME>, some use UpperCamelCase, like <UserName>, or lowerCamelCase, like <userName>. Some standards, like XSLT, use all lowercase, like <xsl:value-of>. There is no uniformity, in contrast to, for instance, Java, where everybody more or less adheres to the same writing and coding rules.

So should we have a standard and what should it look like? Let’s explore.

Why coding standards?

Before writing this Blog I re-consulted the excellent book “C Style: Standards and guidelines” by David Straker, written in 1992. The C programming language might be a bit out of fashion, the general parts of the book still hold. David Straker thoroughly answers questions like: Why do we need standards and what should these look like.

I will not repeat all he has to say about it, but the baseline is: Coding standards are for humans. To make life as a designer/programmer easier. To make things more understandable for somebody else (or yourself when you revisit the code after a year or so).

A good standard takes human psychological limitations into account. For instance, computers don’t give a damn, but for humans <CustomerContactPersonUsernameCodeAbbreviation> is easier to read than <customercontactpersonusernamecodeabbreviation>. And a standard with just a few (good) rules is easier to follow than an extensive document with umpteen pages.

How exactly do (well designed!) coding standards help?

  • As a designer/programmer, you no longer have to think about simple things. Thoughts like “Shall I write this in upper or lower case?”, “I created something like this a week ago; .I want to stay consistent, so what rules did I use to name it?”. In short, it frees parts of your mind to think about more important things.
  • Reading somebody else’s designs or programs or whatever becomes much easier: You can recognize things in the way they are written or layed-out.

What shall we standardize?

Just a few lists with things we might (or might not) standardize:

Basic XML:

  • Basic naming rules for elements and attributes
  • For common types/usages prefixes or suffixes? For instance, I end the names of attributes that hold an identifier always with id (e.g. userid="…") and attributes that refer to an identifier with idref (e.g. currentuseridref="…")
  • Namespace names (and prefix?)
  • Maybe lay-out for comments…?

XML Schema (XSD):

  • Type and group names (maybe something that distinguishes between simple and complex types, attribute and element groups)
  • Versioning of schemas (a very tricky subject)
  • Usage of container elements on repeating data (do you always need a <Customers> element around multiple <Customer> records?)

XML Transformations (XSLT):

  • Variable/Parameter names
  • Named template names (and for XSLT 2.0: functions)
  • Modes

And so on, and so forth.

My standards

The way I design and write my XML is (after all these years) still developing. However, some things seem to have settled. For what its worth:

  • Element names in UpperCamelCase (<UserName>, <CarModel>)
  • Attributes in all lowercase (username, isvalid)
  • An attribute that is an identifier ends with id (userid, carid)
  • An attribute that is a reference to an identifier ends with idref (currentuseridref, modelidref)
  • For XML schemas I use “Hungarian style” prefixes like t for a simple type, ct for a complex type, g for a group, etc.
  • In XML Transformations elements (variables, templates, etc.) I use the UpperCamelCase convention. Modes always start with the word Mode.

To stay consistent, I have a document (which has the permanent status “working copy”, or “in progress”) in which I, now and then, write these kinds of things down. For me it’s the only way not to forget what I have decided about these things in the past.

Bottom line

IMHO:

A standard, even a simple one, is better than none at all.

Some standards are better than others.

Creating a good standard is balancing between too much and too little.

Its not necessary to have a “global” standard, but each company that is serious about its XML should have one.

 

Advertisements

Leave a Comment »

No comments yet.

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Blog at WordPress.com.

%d bloggers like this: