Holy wars

I’m not talking about battles waged in the name of faith and religion here. Being prone to hyperbole, developers have come to use this term to describe the personal reasons for why they prefer one thing over another. For instance, laying out their code in K&R or Allman style. Coding using vim, emacs or nano editors to write PHP, Ruby or Python augmented with Prototype or jQuery.

The mother of all Holy wars is the eternal battle between indentation using tabs or spaces. So deep is the chasm that people take the time to invent new technologies like elastic tabstops or SmartTabs. But I digress. I’m not here to argue for one over the other1 but to point out that people are split into two distinct camps and if you’ve written some clever coding tool that could be useful it’s your responsibility – nay, duty – to take both worldviews into account. Unfortunately not everyone agrees.

Stubbornly asinine comments like this from Tobie Langel are a case in point.

This specific example came to the fore this week when a colleague and I took it on ourselves to wrangle the woefully poorly documented2 PDoc JavaScript tool into our workflow. Our company coding standards call for code to be tab indented so all kinds of errors messages were thrown when we first tried to produce documentation using PDoc.

We put on our detective hats to find the root of the problem and traced the issue back to the Treetop PEG. If you too are pragmatic and care about indentation agnosticism then fire up your editor of choice, browse to the pdoc directory in your Ruby gems location and edit the lib/pdoc/parser/treetop_files/basic.treetop file.

Read on to see how we edited the file to allow for tabbed indentation. I’m not 100% that this won’t have undesired effects on the resulting documentation produced. If you are more familiar with this then please contribute in the comments.

grammar Basic
  rule test_base
    (blank_line / text_line / comment_start / comment_end / line / line_break / space / tab / char)+
  end

  rule blank_line
    line_break (tab* / space*) line_separator space* &(line_break) <blankline>
  end

  rule text_line
    line text:char+ <textline>
  end

  rule line
    line_break (tab* / space*) optional_space line_separator (space / line_break) <line>
  end

  rule comment_start
    line_break (tab* / space*) "/**" space* <commentstart>
  end

  rule comment_end
    line_break (tab* / space*) "**/" space* line_break <commentend>
  end

  rule line_break
    [n] <linebreak>
  end

  rule line_separator
    "*"
  end

  rule char
    ![n] . <char>
  end

  rule space
    " " <space>
  end

  rule optional_space
    " "?
  end

  rule tab
    [t]
  end
end

1 If you must know (and havent’ already guessed), I fall firmly on the sides of K&R/1TBS style with tabs for indentation to cater for individual preferences and only use spaces for alignment of continuation lines.

2 Kind of ironic huh?

Related Posts:

  • No Related Posts