polarmobile / coffeescript-style-guide Goto Github PK

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.

When declaring a function that takes arguments, always use a single space after the closing parenthesis of the arguments list:

foo = (arg1, arg2) -> # Yes
foo = (arg1, arg2)-> # No

I prefer the (a) -> (space) style (I think), possibly mainly because most (all?) CoffeeScript code I've seen uses it. However, I recently ran into this problem:

I wanted to do this:

asyncFunc (result) ->
  console.log result

But I somehow messed up and lost a space:

asyncFunc(result) ->
  console.log result

Woops! Still valid code, though, but now it does something entirely different. Took me some time to spot.

If I had used a (a)-> (no space) style, I could have solved it much faster, since the following is a syntax error:

asyncFunc(result)->
  console.log result

Luckily, many (async) functions take another argument first.

asyncFunc 3000, (result) ->
  console.log result

Any thoughts?

It's obvious that extending native objects is bad if you're doing it improperly:

String::capitalize = ->
  this[0].toUpperCase() + this[1...]

console.log char for char of 'str'
# => 0, 1, 2, capitalize

But ES5 has Object.defineProperty, which allows you to extend objects with non-enumerable properties:

Object.defineProperty String, 'capitalize' value: ->
  this[0].toUpperCase() + this[1...]

console.log char for char of 'str'
# => 0, 1, 2

This is a serious gotcha that a style guide would do well to document (and forbid):

jashkenas/coffeescript#3958 (comment)

try 1/0

suppresses the exception.

I propose amending Exceptions to say "Do not suppress exceptions. Do not use try without catch nor finally, which is an undocumented and surprising way to suppress exceptions."

I just learned coffeescript, How do I set the indent to 4 spaces?

We're having an internal discussion on our team about the best practice for handling docstrings. In Python, we'd do something like:

"""This is a module level docstring."""

class SomeClass(object):
    """This is a class level docstring."""

   def some_method(self, arg1, arg2):
       """This is a method level docstring."""

In coffeescript, we'd like to mimic the pattern:

### This is a module level docstring. ###

SomeObject =
    ### This is an object level docstring. ###

    someMethod: ->
      ### This is a method level docstring. ###
      ...
      # Some inline comment
      ...

I like this approach as it distinctly separates "docstrings" from inline comments, but it appears that triple ### renders a multi-line comment to the compiled javascript -- which is probably undesired in most cases.

Any guidance would be helpful - thx :)

There are several issues with the way that the style guide currently describes how comments should be written. In general, a literate programming style is encouraged (but certainly not mandated). However, the current guide is not compatible with said literate programming style.

The following is a summary of issues as logged by @jashkenas, moved here from ticket #2:

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.

I have often used two spaces for coffee script because of recommendations from others, however with literate coffee script it seems I need 4 spaces for it to work properly? Is this always the case and why use two spaces in the first place?

I found your coffeescript styleguide looking for advice on multiline function calls, but I don't see this topic covered in the guide. Any advice on which of the following is more idiomatic?

aLongFunctionName firstLongArgumentName, secondLongArgument,
thirdArgumentIsAnObject: 'bar'

aLongFunctionName firstLongArgumentName, secondLongArgument,
  thirdArgumentIsAnObject: 'bar'

Also, while we're at it, when creating objects, which of these is more idiomatic?

foo:
  bar: 'baz

foo: bar: 'baz

Thanks for your work on the style guide, it's extremely useful to have a standard.

We are through a debate about the optional commas when defining an array or object, see the examples in the coffeecript docs:

song = ["do", "re", "mi", "fa", "so"]

singers = {Jagger: "Rock", Elvis: "Roll"}

bitlist = [
  1, 0, 1
  0, 0, 1
  1, 1, 0
]

kids =
  brother:
    name: "Max"
    age:  11
  sister:
    name: "Ida"
    age:  9

The documentation explicitly says the commas are optional, and here resides our doubt. We would like to hear some community opinions, is there any rules, thumbs up that you apply to your code? Should this be added to the style-guide in some way?

Regarding the code we can see from coffeescript whenever there is a new line the comma is omitted.

Here we have both opinions:

1. When each property is listed on its own line there is no need for commas as the indentation provide enough readability.
2. The commas are an enforcement to understand the continuation, even when there is a new line. Besides commas are not optional in ruby or python, since coffeescript is heavily based on those it makes sense to maintain this as a style "rule".

We would love to know your opinion regarding this.
Thank you!

http://blog.polarmobile.com/2011/12/coffeescript-style-guide

We should add a recommended set of options for @clutchski's CoffeeLint to the style guide.

Thanks @shanejonas for the idea.

Hey in the section Module Imports it's mentioned to order your imports by:

1. Standard library imports (if a standard library exists)
2. Third party library imports
3. Local imports (imports specific to this application or library)

in the example it's written:
require 'lib/setup'
Backbone = require 'backbone'

But isn't "require 'lib/setup'" a local import and "Backbone = require 'backbone'" a third-party library? If this is correct one should switch the order in the example.

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!

CoffeeScript 1.3.1 made or= a syntax error. Conditional assignment should be made with the ?= operator.

This is relatively minor, but since 2 spaces is in bold, it seems to imply that you should strictly use only 2 spaces for indents.

I personally prefer 4 spaces as I find 2 spaces to degrade readability (which is one of the primary benefits to using CoffeeScript). Is there a technical reason as to why 2 spaces is better than 4? Or should the style guide be changed to say "2 or 4 spaces per indentation level"?