Some functions (mainly the ones that modify variables directly) take a variable name, while others take a value (hence the dollar $).

Yes, I know this. The problem is that that it's not always consistent... Though I'm concluding that if you're passing an array or a list it's usually just the name.

As for comments, the docs clearly state that the # has to be the first non-space character in the line, otherwise it is just another token for the parser to deal with (confusing, I agree).

I have discovered this. You can't have something like:

set fingers 10 #number of fingers

However, what I was referring to was something along these lines:

if { $foo > 10 } { 
#was: if { $foo > 8 } {
  ...stuff...
}

Not exactly the code, of course, wish I had the exact code around still. Messy, yeah, but I was trying something out so I commented one of the if's. But that led to some kind of syntax error. To get it to work I ended up having to get rid of the '{' at the end of the commented line. That's a real sloppy parser they've got there. (speaking of which, I was examining a Tcl file that had been checked in for months and was released in our product (written by Tcl experts, not I) and I noticed in Vim that there was an unmatched " (with syntax coloring on it was quite obvious). Yet it had compiled and run fine. I removed the errant " and the output of the program was the same. I sat there stunned... Again, that's quite a parser they've got there.

All vars are locally scoped by default. So, to access them from within another scope (like a proc), you need to either declare them as global (yuck) or reach out to the parent scope and grab them (upvar)

Ummm.... OK. So it's a global that's just not quite as global.... err... I'm still trying to understand when people use these sort of "cheats" (for lack of a better word). It just seems so messy.

Anyway, my post is to show you that there is some thought behind Tcl's design.

Oh, I'm sure there was some kind of "thought" that went into it... I just find myself not agreeing with much of the "thinking". Tcl feels like had all kinds of stuff tacked onto it with bubble gum in order to make it stick together. upvar is one of the more prominent examples - I'm guessing you wouldn't need that if you had true lexical scoping. Let's just say that language design wasn't the forte of the creator of Tcl.

As with any language, if you don't like it, choose something else. Cheers.

Unfortunately, we've got a lot of legacy Tcl code and I am one of the inheritors. Most of the time I can be blissfully unaware of it... until something goes wrong...

And lest you think I'm completely negative, I will praise Tk. I still think it's one of the better GUI toolkits out there; I especially like it's canvas widget. This is probably the reason that Tcl got the mindshare it had (well, that and expect).