Mismatched braces in comments

[Jonathan Bromley]

This is embarrassing.

For a while I have been aware of some folklore that says
"avoid mismatched braces in comments". I even tell students
exactly that. I know it's a bad idea. But I absolutely fail
to understand what's going on. Maybe I'm being dim, but my
reading of the endekalogue sheds no light on why this is
erroneous:

proc wobbly {} {
puts wobbly
# }
}

and, apparently, this is not:

proc floppy {} {
set a junk
# foreach a {b c d} {
puts $a
# }
}

and, even more alarmingly, this is OK too:

proc collapsible {} {
set a junk
foreach a {b c d} {
puts $a
# }
}

Can someone who understands kindly humour me and
explain what's really going on? All my examples
tried in Tcl 8.4.6, but surely that shouldn't matter?

Many thanks
--
Jonathan Bromley, Consultant

DOULOS - Developing Design Know-how
VHDL * Verilog * SystemC * e * Perl * Tcl/Tk * Project Services

Doulos Ltd., 22 Market Place, Ringwood, BH24 1AW, UK
jonathan...@MYCOMPANY.com
http://www.MYCOMPANY.com

The contents of this message may contain personal views which
are not the views of Doulos Ltd., unless specifically stated.

[Donal K. Fellows]

Jonathan Bromley wrote:
> Maybe I'm being dim, but my
> reading of the endekalogue sheds no light on why this is
> erroneous:
> proc wobbly {} {
> puts wobbly
> # }
> }
> and, apparently, this is not:
> proc floppy {} {
> set a junk
> # foreach a {b c d} {
> puts $a
> # }
> }

The problem is that you're thinking like a person, not like the Tcl
parser. Remember that the Tcl parser parses one character at a time,
and that it also parses each character once (unless told to re-enter)
and this is a case where this really matters.

When it's parsing the first example it comes across a { at the start
of a word and starts looking for the matching }, which it finds on the
line with the # (which isn't a special character at this point; Tcl's
not looking for the first word of a command). The } after that is just
an ordinary character (unless embedded in something larger) and I bet
you haven't defined a command called that... :-D In the second
example, the parser doesn't find matching } until it's processed the
line on its own, which corresponds to a "correct" parse in the way you
think about things.

Note that we can rewrite the first example like this:

proc wobbly {} "
puts wobbly
# }
"

Well, except that the parser won't be getting confused.

Donal.

[sleb...@gmail.com]

On Oct 7, 4:45 am, Jonathan Bromley <jonathan.brom...@MYCOMPANY.com>
wrote:

It has to do with the order of processing the script which is roughly
as follows:

First word boundries are located. To get word boundries, groupings
also need to be parsed so it is at this point that "" and {} are
parsed.

Second substitutions occur where needed.

Finally commands are executed. If the first character of the command
is # then it is treated as a comment. Yes, you read that right,
comments are parsed last.

And you cannot really change this because this is the only way to
properly distinguish comment from data. The following are properly
valid code where the string following a # isn't a comment:

# set the background color of a widget:
.widget configure -bg #cccc99

# print a poor-man's progress bar on screen:
puts #

# a bit of HTML:
set message {<font color="#22aa99">Hello</font>}

This is also the reason why it is so hard (I'd say impossible) to
write a correct syntax coloring algorithm for Tcl.

[Jonathan Bromley]

On Sat, 06 Oct 2007 21:45:01 +0100,
Jonathan Bromley <jonathan...@MYCOMPANY.com> wrote:

>This is embarrassing.

Certainly is. First, thanks to both of you for the lucid
clarification. Second, thanks to comp.lang.tcl for providing
the usual opportunity to spot an answer for yourself, ten
minutes after posting a query :-)

>For a while I have been aware of some folklore that says
>"avoid mismatched braces in comments".

and, in summary, the answer is that the boundaries of
proc arguments are parsed *before* comments; if an
argument happens to be a script, then the comments
inside it are not examined at all until the proc gets
around to executing its body. I assume this is all
modulo some bits of business about the bytecode compiler,
but I also assume that this is pretty much hidden from
script authors.

I can't help feeling, though, that the bald description of
comments in the endekalogue could use a little clarification.
The "problem" I described really isn't at all obvious. As
Donal said,

> The problem is that you're thinking like a person,
> not like the Tcl parser.

Thanks again

[suchenwi]

My rules of thumb for Tcl comments are:
- use sparingly, let the code document itself :^)
- comment out blocks of code with if 0 {...}
- *never* put comments in [switch] tables
- (mostly) rely on emacs brace matching/autoindent to see problems

[Tom Conner]

"suchenwi" <richard.suchenw...@siemens.com> wrote in message
news:1191752437.2...@k79g2000hse.googlegroups.com...

> My rules of thumb for Tcl comments are:

> - *never* put comments in [switch] tables

I always get a smile (in hindsight) when I take my working code and break
it. More than once I can remember looking over some "old" code and
thinking, "This needs a comment". So, I add a perfect comment, that is
cosmetically integrated into the code. Later I realize that the program is
crashing. Now what, I think. After troubleshooting, it turns out I added
the comment inside a 'switch' block. Curses. Foiled again.

[Pavel Novozhilov]

On Oct 6, 4:45 pm, Jonathan Bromley <jonathan.brom...@MYCOMPANY.com>
wrote:

> This is embarrassing.
>
> For a while I have been aware of some folklore that says
> "avoid mismatched braces in comments".

There a pretty good wiki page http://wiki.tcl.tk/462
Turns out it's for a reason.
Pavel.