polarmobile/coffeescript-style-guide — Issue #2: Style Guide Corrections ;)
Author: jashkenas
Created: 2011-12-19 20:00:08+00:00
State: open

Instead of doing this in a fork -- I'd rather put these in a ticket to make conversation easier...

* Do not use more than one space around these operators:

# Yes
x = 1
y = 1
fooBar = 3

# No
x = 1
y = 1
fooBar = 3

... I think this particular point is still fairly undecided. There are a lot of sequences of CoffeeScript where aligning your left and right values to look more like a table is pleasing. I know a style guide has to pick one way or the other, but I think it's still an open question.

------------------

test: (param=null) -> # Yes
test: (param = null) -> # No

Nope -- quite the opposite. If `a = b` should always be written with spaces around the `=`, then the same holds true in default arguments, Python notwithstanding.

-----------------

Ideally, improve the code to obviate the need for the
comment, and delete the comment entirely.

Actually, CoffeeScript tries to encourage pervasive commenting ... not so much to answer the "what" or the "how" of any individual line of code, but to answer the "why".

If a comment is short, the period at the end can be omitted.

Nope -- comments should be written as full sentences, with proper punctuation.

-----------------

The bit that you describe as "block comments" aren't CoffeeScript block comments, which look like this:

###
comment
###

... but, the ones that you describe are always preferred instead of block comments -- which should only be used if you intend to pass along the comment to the underlying JS, like a license, or warning.

---------------

The use of inline comments should be limited, because their existence is typically a sign of a code smell.

Nope -- poor comments are poor, and good comments are good. There's no problem with writing good inline comments to explain an un-obvious function or tricky algorithm.

----------------

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.

---------------

When calling functions, omit the parentheses on the final method call in a chain.

I think that parentheses inclusion or omission doesn't have a hard and fast rule. For example, your second example doesn't benefit:

foo(4).bar(8) # ... is probably more readable than:
foo(4).bar 8

Usually, it should be obvious (or at least obvious-ish) when leaving parentheses (and braces) off makes things clearer, and when it doesn't:

brush.ellipse x: 10, y: 20

obj.value(10, 20) / obj.value(20, 10)

print inspect value

new Tag(new Value(a, b), new Arg(c))

-------------------

The correct way to apply the function grouping style when chaining is to use it for the initial call only.

I personally don't use it, or recommend it, but I would think that folks that do prefer it would take issue with this rule.

---------------

Finally, you may want to add a note to always avoid use of standalone `@`, all by itself. A simple `this` is preferred. (A common question.)

-------------

Thanks for this style guide -- it's really great stuff.