Coding style in tag-based languages

HTML is typically formatted to show structural containment:

<h1>Topic</h1>
   <p>Some paragraph.</p>
   <p>Next para.</p>
   <ul>
      <li>item 1</li>
      <li>item 2</li>
   </ul>

Code is typically formatted to show flow-of-control:

node = tree.append "Topic 1"
node.append "Some paragraph."
node.append "Next para."
list = tree.append "Unordered"
items.each { | i |
   list.append i
}

One reason that tag-based languages can lead to such confusing pages is that they are often formatted both ways:

<h1>Topic</h1>
   <p>Some paragraph.</p>
   <p>Next para.</p>
   <ul>
      <% items.each { | i | %>
         <li><%= i =></li>
      <% } %>
   </ul>

The purpose of formatting is to make structure apparent, not to slavishly increase the amount of whitespace in the world. Since the page is primarily the UI designer’s domain, I think that flow-of-control ought not to be indented in tag-based pages:

<h1>Topic</h1>
   <p>Some paragraph.</p>
   <p>Next para.</p>
   <ul>
      <% items.each { | i | %>
      <li><%= i =></li>
      <% } %>
   </ul>

I’ve tried to make the difference more explicit in this image. Note how the 2nd sample, which combines indenting styles, has control-flow indenting (in blue) which I recommend eliminating:
indent

Update: A more programmer-like thought is something alone the lines of “Control-flow on a page ought to be encapsulated,” but I don’t think the design tools of designers are capable of rendering componentized snippets, which I think is why designers are so darned resistant to them.

13 thoughts on “Coding style in tag-based languages

  1. Pingback: Twitted by elijahmanor

  2. I feel the pain too, but I don’t think dropping flow-of-control indenting like you suggests makes it any better.
    It might be the case for a simple example like this but the truth is that any reasonably sized or reasonably complex (more than one code block) will be just as flicked up to understand.

    Mixing code and html usually leads to horrible results.

    Have you tried HAML?
    I think it could help a lot in this case.

    At the top of my head, after a long night without sleep, here’s how i think it would be:)

    %h1 Topic
    %p Some paragraph.
    %p Next para.
    %ul
    – items.each do | i |
    %li= i
    %p next para.

    If only for removing the lots of angle brackets (opening AND closing), it already makes it much cleaner.
    It also has meaningful spaces, so they ALWAYS means structure.

    IMHO, it’s, at the very least, much more tolerable than its HTML counterpart

  3. Cool, the comments stripped white space!
    Here’s how it was supposed to be:

    %h1 Topic
    %p Some paragraph.
    %p Next para.
    %ul
    ..- items.each do | i |
    ….%li= i
    %p next para.

    =~ s/\.\./\u0020\u0020/g;

  4. Whoops, looks like all my sample got filtered. I’ll try it again:

    <h1>Topic</h1>
    …<p>Some paragraph.</p>
    …<p>Next para.</p>
    …<ul>
    ……<for each=”var i in items”>
    ………<li>${i}</li>
    ……</for>
    …</ul>

    (Updated by Larry to show spacing)

    You have no preview mechanism so I apologize if this looks like crap!

  5. I lean the opposite way. Structure in tag soup generally gets nested far more than control flow ever does, so there’s often negatives as well as positives to being methodical about the indentation; and whitespace can be significant, so you can’t even do it all the time even if you wanted to.

    Control flow on the other hand is usually pretty important; if you have several nested loops, it helps to see them clearly. The chunks of the structure will generally be implicitly part of the loops anyway.

  6. Pingback: uberVU - social comments

  7. To my eye, the purpose of indentation is not to boost the market for extra-wide monitors, but to provide visual indicators that allow the reader to “chunk” what they see correctly. Tag-based markup AND programming languages are fundamentally a tree-shaped things not linear things, and the indentation helps us to show that tree shape.

    That being said, the person reading the file almost certainly cares about BOTH the tree-shaped tag structure (because they’re trying to author the tags) and ALSO about the tree-shaped block structure of the flow control (because they care about things like “what part repeats” or “what part appears only in certain conditions). So I prefer to indent whenever EITHER occurs, so as to show both kinds of tree-structure.

    There is one exception, and that is when the two tree are not properly nested. For instance, you might have “” then some content followed later by “”. So the content always appears, but it might or might not be wrapped in an extra . Personally, I solve this by insisting that the trees ALWAYS be properly nested: in this case I would always use the and make only the class be optional. (But every once in a while I am unable to follow this rule because of special circumstances.)

  8. Pingback: Knowing .NET » Blog Archive » Coding style in tag-based languages

  9. Pingback: Coding Style in Tag-Based Languages « From Big Island (FBI)

  10. Pingback: Interesting Finds: 2009 11.17 ~ 11.22 - gOODiDEA.NET

Comments are closed.