To Comment or Not to Comment?

Lindsay Hill wrote an article on iRules comments on his site that got me thinking about comments in general. As I prepared to just bring forth some insightful commentary on using comments in iRules, the majority of the quotes I found are actually bent against commenting in code. My favorites:

Good code is its own best documentation. As you’re about to add a comment, ask yourself, ‘How can I improve the code so that this comment isn’t needed? - Steve McConnell

Every time you write a comment, you should grimace and feel the failure of your ability of expression. - Unknown

I'm more than a little knotted up over this idea of not commenting the code. For well-maintained source code in large projects, maybe this is a best practice. For scripts like iRules, however, I'm a big fan of commentary. The reality is that in operational environments, people come and go and, well, even the original author might need a refresher course on what the iRule does after a few (weeks?) months go by and an emergency hits at 3am. Clear documentation in the iRule can go a long way to providing clarity on iRule overall and event/section functionality, especially for the operations on-call looking at not only your iRule for the first time, but perhaps AN iRule for the first time. Another reason for using comments over readable code can be found in #6 of Joe's 10 steps to iRules optimization, which states that longer variable names, whereas making the code more readable, actually have memory implications.

Now that I've waxed philosophically on whether or not to include comments, how do you actually do it? Well, the formal comment  is accomplished with the pound sign. From the Tcl wiki:

If A hash character ("#") appears at a point where Tcl is expecting the first character of the first word of a command, then the hash character and the characters that follow it, up through the next newline, are treated as a comment and ignored. The comment character only has significance when it appears at the beginning of a command.

# single line comment started with the hash or pound sign.
when HTTP_REQUEST {
  log local0. "Request event has fired" ; # in-line comment. Lead with a semi-colon.
}

This is the most commonly seen method of commenting. Something Tcl doesn't support natively like most other languages is the multi-line comment. However, it can be done without commenting each line out. There are many workarounds for this, two of which are shown below.

Option 1

One way to comment out many lines is to use a false condition.

if 0 {
  set x 13
  set y 15
  set product [expr {$x * $y}]
}

Note that using this method will still require all the lines to be valid iRules lines. The syntax validator will allow the previous example as all lines are valid, but will not allow the example below.

if 0 {
  this is a comment and I can
  put anything here that I want
  to.
}

error: [undefined procedure: this][this is a comment and I can]
error: [undefined procedure: put][put anything here that I want]
error: [undefined procedure: to][to]

This is a good option if you want to comment out a large existing section of code quickly to isolate issues in other sections of code.

Option 2

Another way to comment many lines of code is to just to wrap them in a variable. No valid code necessary for this option, as evidenced by a fake command in HTTP::nonsense and a pool that does not exist in undefinedpool. This passed the syntax validator just fine.

set comment {
  this is a comment on multiple lines
  with non-existent commands and objects
  yet will save just fine
  if ([HTTP::nonsense] eq "/test") {
    pool undefinedpool
  }
}

The Fine Print

Whereas both these methods work, I'd recommend only using them during development and/or troubleshooting exercises. Why? Well, with the formal comment, Tcl ignores all that and it doesn't get compiled down to bytecode. That is not the case for these options. The code in the false condition will never run and the variable may never be called, but both approaches unnecessarily consume system resources. The first option consumes memory and runtime resources, the the second option only memory.

Oh, one more thing. Even in these methods, you need to match your brackets or the syntax validator will complain. Note that this is true even with the formal comments as well when strung together.

What other approaches to multi-line comments in Tcl/iRules have you seen or used? Drop a #comment below!