polarmobile / coffeescript-style-guide Goto Github PK
View Code? Open in Web Editor NEWBest-practices and coding conventions for the CoffeeScript programming language
Best-practices and coding conventions for the CoffeeScript programming language
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"?
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:
We would love to know your opinion regarding this.
Thank you!
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.
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."
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.
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.
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:
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.
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?
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 :)
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.