How to name constants; top-level variables and naming collisions

[showell]

It might be worth mentioning a strategy to avoid naming collisions between variables at the top level scope of your file and local variables within more narrow scopes.

Some of this is already implicitly covered--if you name your classes CamelCase and your constants ALL_CAP_CASE, then you're unlikely to accidentally alias local variables.

If you have functions at top level scope, then there can be gotchas if they have the same name as local variables.

Thanks for publishing the style guide!

[mjrusso]

To simplify the overall discussion, I would like to broaden the scope of this ticket to include some of @jashkenas' comments from #2 re: the naming of constants:

For constants, use all uppercase with underscores

I don't think that this one is settled quite yet. In JavaScript, of course, until const lands, there's no such thing as a constant. For that reason, I think that simply using local variable style for constants may actually make more sense. I'm not sure which should be prescribed.

[showell]

I see the point that @jashkenas makes. I know that JS doesn't enforce true constants, but I like the ALL_CAPS convention for variables that are effectively read-only. Certainly, things like PI or FACEBOOK_API_ID should be ALL_CAPS, correct?

The biggest challenge for naming collisions is function names at top level scope. They can collide with local variable names in more narrow scopes. For me, the best resolution is to make sure that function names are distinct from local variable names in general, so all function names should include a verb, i.e prefer calculate_area to area for a function name.

[jashkenas]

So, perhaps the style guide should say that although there is no such thing as a constant in JavaScript ... if you're using a variable as a constant, you may choose to put it in ALL_CAPS to communicate this.

@mjrusso: By the way, if you end up publishing this style guide online in a pretty HTML version (I'd recommend using the gh-pages branch), I'd be glad to link to it from coffeescript.org

[showell]

@jashkenas Yup, I think that's a good way to word it...put the emphasis on the fact there are no such things as a constant, and say that ALL_CAPS is only a convention or hint of intent.