Guidelines: Code Readability - Pt1

At work I (with heavy input from the rest of the team) am writing these guidelines for our development practices, so that everyone is working 'on the same page.' I will share this series here for others who may want to know how some folks do it.

In everything there must be balance, two sides to every coin. A debate goes on about code "structure". To indent? Or not indent? One argument persists that unnecessary spaces/tabs within code increase the bandwidth used by our systems, serving up 'empty' content. The other argument is that this cost is minimal, in comparison to the time savings with relation to maintaining 'readable' code.

Our official position is that the maintainability of code is more important. At some juncture, in the future, we may implement other methods for reducing the 'space', possibly eliminating it during the Ant build process during deployment. For now it is more important to be able to quickly scan code, find items for clarification or change, and accomplish our mission.

Proper indentation of code does assist in the maintainability of the code, and should be applied regardless of the language being used (XHTML, ActionScript, JavaScript, SQL, ColdFusion, etc.) Indentation should be applied to logical blocks of code within a document. The following are a few different examples:

ColdFusion CFC:

Most documents, of any type, will have very similar, base level code stylization. The following example is for a standard ColdFusion template. Most nested elements/tags will further increase the indentation, though there will be exceptions.

ColdFusion CFM

From the previous example, you see a number of examples simultaneously. We start with the standard comment header, come to some processing directives, then get into actual output. The entire document is wrapped within a <cfsetting> tagset. These tags, at the beginning and end of the document, are open (or self-closing) tags, the first stating that any document content after the tag should only be displayed if it is within an explicit output block (either <cfoutput> or a WriteOutput() statement). The second <cfsetting> tag opens the document for non-explicit output, in case this template is included inside another document. By usinging the enablecfoutputonly attribute, the server will reduce the amount of whitespace rendered in the XHTML passed to the browser. Another tool for this is the use of the <cfsilent> tags. Here they are wrapped around a multi-line ColdFusion comment, which would be processed as whitespace to the XHTML document (The above example is for example use only. The above comment would have typically been outside the <cfoutput> altogether). By using the <cfsilent> tags around this, we eliminate that whitespace generation. These tags are also handy if you require a processing block in the middle of your output, as it will hide the whitespace that processing block would produce.

The example above also shows that there are times when you should, and should not, indent. With ColdFusion, JavaScript, ActionScript, etc., simple conditional output (if this then "ok") will typically be inline, while more complex conditional output will be indented as normal. Any looping conditionals will be indented. There are examples above for both tag based, and simple scripted programming.

Our next post will be part II of this topic, where we will show more examples covering XHTML, script, and SQL examples.