Syntax conventions for ConciseXML

Indentation Rules

Use spaces for indentation, never use tabs. Editors should insert spaces when the tab key is pressed.

Summary on how many spaces to indent?

If a call (XML element) spans more than one line, then the end of the call should always line up under beginning of the call.

Example: 
<do
 <thing/>
/>
Example: 
<do>
 <thing/>
</do>

Alignment of the beginning and end is very important -- even if the start of the call is indented.

Example: 
<bar xxx=<thing x=10
                y=100
         />
     yyy=20
/>

Here is an example of HTML

Example: 
<TABLE>
 <TR>
  <TD>
   xxx
   yyy
  </TD>
 </TR>
</TABLE>

The exception to the vertical alignment rule is when there multiple calls are started on the same line or closed on the same line. In this case, the first closing lines up vertically with the first call start.

Example: 
<TABLE><TR><TD>
 xxx
</TD></TR></TABLE>

The calls below start on different lines, but end all on the same line which is acceptable.

Example: 
<TABLE>
 <TR>
  <TD>
 xxx
</TD></TR></TABLE>

One option is to put unkeyed and/or required arguments on the first line, then put each keyed argument on separate lines.

Example: 
<class foobar
  xxx="value"
  xxx="value"
/>

One space when indenting the content of a tag:

Example: 
<stuff arg1="more stuff">
 <more stuff/>
 "other_stuff"
</stuff>

Simple nesting of expressions

Example: 
<foo
 <bar xxx=10 yyy=20/>
/>

Deep expression nesting

Example: 
<foo
 <bar xxx=<thing x=10
                 y=100
          />
      yyy=20
 />
/>

Use two spaces to indent arguments from the start of the call. If the opening tag spans more than one line, indent the second and following lines.

Example: 
<stuff arg1=null arg2=null arg3=null
  arg1=null arg2=null 
  arg3=null
/>

Optionally, the arguments starting the second line can line up the start of the arguments on the first line.

Example: 
<stuff arg1=null arg2=null arg3=null
       argument4=null arg100=true
/>

If tag with content has an opening tag spaning multiple lines, the closing angle is directly below the opening angle bracket. Although unconventional, this avoids the confusing attributes with elements.

Example: 
<TABLE height=100
   color="red"
>
 stuff
</TABLE>

Long paths can be continued on the next line and are indented exactly 3 characters:

Example: 
customer_A.orders.123.<get_stuff x=10/>.
   line_items.3.<get_price/>

For paths containing calls spanning multiple lines, there are several options. The ending tag can align with the start of the path.

Example: 
customer_A.orders.123.<get_price
  1000
  id=2333
/>.<length/>

Alternatively, the closing tag can be aligned with the start of the tag.

Example: 
customer_A.orders.123.<get_price 1000
                        id=2333
                      />.<length/>

The call within a path can start a new line and be indented by 3 characters. The closing tag is directly underneath the start of the tag.

Example: 
customer_A.orders.123.
   <get_price 1000
              id=2333
   />.<length/>

Concise closing tag

Use a closing tag unless the tag fits on one line.

Example: 
<TR><TD>stuff</><TD>other</></>

Avoid using 3 or more concise closing tags in a row. A named closing tag should be used instead of seeing three unnamed closing tags.

Example: 
<TR><TD>stuff</><TD><B>other</></></TR>

Conventions for special tags

Line spacing

There should be an empty line before and after each method and class.

Example: 
<class foo>

 <method bar>
  null
 </method>

 <method to_html>
  "stuff"
 </method>

</class>

<class yum>
 null
</class>

If the attributes of a class or method don't fit on a single line, it is recommended to put each parameter on a separate line. Lines with attributes should be indented two spaces.

Example: 
<class person
  last_name="Newell"
  age=26
/>

The equal-sign can be aligned by spaces if desired.

Example: 
<class person
  last_name="Newell"
  age      =26
/>

The field key can optionally be right-aligned so that the equal signs are vertically aligned.

Example: 
<class person
  last_name="Newell"
        age=26
/>

An exception to the 2-space indentation for attributes is when 'do' is used. When using 'do', a single space indentation is used.

Example: 
<do
 <this/>
 <that/>
/>

Do

For non-conditional, one-pass flows, use:

Example: <do "..." />
Or use a named closing tag when there are many expressions in the content area.
Example: 
<do 
 <foo/>
 <bar/>
></do>

For conditional flows using repeat, while, until use:

Example: 
<do> 
 <while x.<less 10/> /> 
 ...
</do>

Attribute spacing

Do not put spaces around '=' in attributes, unless you are aligning multiple attributes. The exception is when using 'set'.

Use one space between attributes.

Set

Use spaces around the equal sign for 'set'.

Example: <set x = 10/>

When multiple fields are 'set', each pair of key and value should be on their own line.

Example: 
<set x = 10
     y = 20
/>

To improve readability, the key can be indented so that the equal-signs are vertically aligned.

Example: 
<set a_obj = 10
     y     = 20
/>

The attributes can be indented two spaces and the first one can be put on the second line.

Example: 
<set
  a_obj = 10
  y = 20
/>

When the value spans multiple lines, put the key on one line and the value on the next line.

Example: 
<set new_posting_instance =
  <post
    where="here"
    when="now"
  />
/>

If

If only one short condition-action pair, can put on one line.

Example: <if> condition1 action1 </if>

Avoid using 'do' for a condition or action that is only one expression. The following is NOT recommended because it puts a single expression in a 'do' block, which tends to hurt code readability.

Example: 
<if> condition1
     <do
      action1 
     />
</if>

If 'if' has one or two condition-action pairs that fit on a single line, put two spaces between the pair.

Example: 
<if> condition1 action1  else action2 </if>

If there are more than 2 condition actions, always the condition and action on separate lines. Indent the action 2 spaces from the condition.

Example: 
<if> condition1
       action1
     cond2   
       action2
     else 
       <do
        something1
        something2
       />
</if>

Alternatively, the first condition can be put on the second line:

Example: 
<if> 
  condition1
    action....
  condition2
    action2
  condition3
    action3
</if>

If adding a blank line between the pairs improves readability, then add the extra space between every pair.

Example: 
<if>
  long_condition.....................
    long_action....

  cond2
    action2
</if>

Naming conventions

Use all lowercase for classes and methods.

Static HTML symbols in uppercase. When formatted, tags are always printed in lower-case.

Attribute keys are lower-case.

System attribute keys start with a underscore.

For local variables: ones that hold instances, use "a_" concatenate with class name:

Example: a_thing=<thing/>
When used more than two times, use 1 to 3 letter abbreviations.
Example: 
<set AR = <get_accounts_receivables/>
     GL = <get_general_ledger_transactions/>
/>

Avoid using any abbreviation that is also an HTML tag name. For example, do not use these letters (uppercase or lowercase) for variable names: 'a', 'b', 'i', 'p', or 'q'.

Parameters that have names in common with a class, use: "a_" concatenate with a class name:

Example: 
<uri a_uri="http://www.clearmethods.com"/>

For multi-word variable names, use underscores between words, not camel-casing. This avoids many case-sensitive errors. and works for foreign languages that do not have the concept of uppercase and lowercase letters. For multi-word names, camel-casing is often harder to read than camel-casing.

Example: 
ThisIsCamelCasing
andThisIsAlsoCamelCasing
this_is_using_underscores_between_word_parts