How should you layout code?

It is strange to see the heat generated over arguments about how code should be formatted. With Visual Studio, of course, it isn’t much of an issue, as it is done for you, but the closer you get to the ‘live free and die’ communities of the LAMP platforms, the more contentious it gets. Likewise, SQL Server’s TSQL inhabits a strange land where there seems little consensus over the correct way to lay it out.

There are some great tools for doing automatic layout of code. Visual Studio sets a high standard for this, but other IDEs have caught up. Visual Slickedit is hard to beat as a general-purpose programmers’ editor, with facilities to tidy up almost any language. Nevertheless, for the most part, each language has its favourite tool. A few examples that spring to mind:

  • A perennial favourite for .NET code is Jetbrains ReSharper, thought by many to offer better formatting capabilities than native Visual studio.
  • For PHP, I’ve always liked Waterproof’s PHPedit, and their command-line phpCodeBeautifier works well and is free.
  • There is nothing to beat HTMLTidy for tackling HTML and XML layout
  • Topstyle is the only tool I know of that sorts out CSS layout properly
  • Aptana studio does a great job in laying out JavaScript.
  • SQL Refactor is an essential tool for untidy SQL Server 2005, programmers. I’ve found very little else to touch it as a SQL code beautifier.

 I was recently re-reading Joe Celco’s excellent book ‘SQL Programming Style’ and it struck me that there really wasn’t much in what he says about the layout of code that one could argue with. However, the feedback that Red Gate gets over the SQL Refactor product is that providing 40 different options for laying out SQL code just isn’t enough.

After years of ‘anything goes’ SQL coding, it is hard to get any consensus on the right way to lay it out. Every large IT department seems to have its own standard, ranging from incredibly strict, to “everything in lower case”. I have a sneaking tolerance towards the latter, liberal approach but, as the editor of a website that has a lot of SQL on it, I have my own reasons to hope for some sort of consensus.

It is worse still for our sister website, SQLServerCentral.com. In this case, people describe their coding problems in forums, and sometimes paste in code that makes one involuntarily flinch. I can see how years of suffering in this way occasionally turns Joe Celco from his usual mild Dr Jeckell persona into a Forum Mr Hyde. Jeff Moden is now famous for his attempts to try to persuade forum users to adopt a Forum etiquette that includes writing SQL that can easily be understood by others.

In short, there would seem to be an obvious need to tighten up standards somewhat. So, how’s this for a suggestion:

Identifiers:

  • No Reverse Hungarian notation
  • Use ISO-11179 where appropriate
  • Up to 30 characters.
  • Avoid abbreviations.
  • Avoid quoted (delimited) identifiers,
  • Use standard postfixes
  • Use only letters, digits and underscores for names
  • Scalars should be in lower case
  • Schema object names should be capitalised
  • Reserved words should be in upper case.

Layout:

  • Use a comma, followed by one space (or newline), as a delimiter in a list.
  • Use one space only between language tokens
  • Use a tab-space of three ems (spaces)
  • Put each clause on a new line, indenting if it is a subordinate clause or subquery.

Disagree? We’d love to hear from you – jsut add your suggestions as a comment to this blog (you’ll need to be signed in). The best contribution will receive a $50 Amazon voucher!

Cheers,

Tony.

  • 3002 views

  • Rate
    [Total: 0    Average: 0/5]