Comments in Tcl can be another source of frustration if the Tcl syntax rules are misinterpreted. Comments look like those in shell-type languages, a line that begins with a “#”. However, Tcl fully parses lines before deciding that they should be executed (in the case of a command) or ignored (in the case of a comment). You should think of a comment as a “do nothing” command, rather than as a comment as in other languages. Comments may appear where Tcl expects a command to appear.

Two common problems arise when comments are included in the arguments of a command or are used to temporarily remove sections of code during testing or development. The switch command illustrates the first problem. Switch arguments include a test string followed by one of more pairs of patterns and Tcl code blocks. The problem in the following example occurs when comments are inserted among the pattern-code pairs:

switch $code {
    # decode red, green, blue color codes
    r {set color red}
g {set color green}
    b {set color blue}
    default {puts "oops, unknown color code"}
}

Since the switch command expects pairs of patterns and code blocks, the beginning “#” of the comment line is interpreted to be a pattern, followed by a code block (literally “decode”), another pattern (“r ed”) with the code block “green,” and so on. Tcl will announce “extra switch pattern with no body” if there is an odd number of words in the comment line, or perhaps yield an “invalid command name” if there is an even number of words in the comment line and a pattern was matched.

The solution is to either move comments out of the pattern-code pairs or include comments in the code blocks, where command lines are expected:

# decode red, green, blue color codes
switch $code {
    r {
        # the color is red
        set color red
    }
    g {set color green}
    b {set color blue}
    default {puts "oops, unknown color code"}
}

Again, note that Tcl does not have much structure. Braces serve to quote a command’s arguments, and nothing more. In the previous example, the comment for the pattern “r” is acceptable because the comment is actually part of code to be evaluated for the pattern and the comment character is found where a command is expected.

The second common problem with comments occurs when they are used to comment out parts of code. It is common during development to add extra code that is alternately commented and uncommented as development progresses. This example shows an extra if command that was used during testing but is now commented out:

proc scaleByTen {x y} {
#   if {$x > 9 && $y > 0} {
    if {$x > 9} {
        set x [expr $x * 10]
    }
    return $x
}

puts [scaleByTen 4 1]
puts [scaleByTen 15 1]

The Tcl parser finds comments only after an entire command line is assembled. The ending open brace at the end of the comment line causes every character to be included until the matching close brace, consuming the entire body of the procedure. Running this code fragment as part of a program will cause a “missing close-brace” error. If you type this code into an interactive Tcl interpreter, Tcl will keep prompting you to finish the command with a closing brace.

The best way to avoid this problem is to ensure that comments look like full commands themselves, accounting for all braces that are contained in the comment.

Sometimes a small comment on the same line as your Tcl code is desirable. Tcl lets you add comments in this fashion; just terminate the preceding command with a semicolon and add a comment. Semicolons are another way to separate commands, in addition to newline characters:

set n {[0--9]};# regular expression to match a digit

Without the semicolon before the comment character, the set command will fail because it would receive too many arguments. Tcl treats “#” as an ordinary character if it is not at the beginning of a command.