{"id":13652166,"url":"https://github.com/polarmobile/coffeescript-style-guide","last_synced_at":"2026-03-15T14:54:43.301Z","repository":{"id":2074460,"uuid":"3013517","full_name":"polarmobile/coffeescript-style-guide","owner":"polarmobile","description":"Best-practices and coding conventions for the CoffeeScript programming language","archived":false,"fork":false,"pushed_at":"2018-11-08T08:05:46.000Z","size":401,"stargazers_count":1633,"open_issues_count":18,"forks_count":270,"subscribers_count":61,"default_branch":"master","last_synced_at":"2025-12-20T11:40:34.403Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/polarmobile.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-12-19T17:07:58.000Z","updated_at":"2025-12-10T16:34:32.000Z","dependencies_parsed_at":"2022-09-07T12:02:02.581Z","dependency_job_id":null,"html_url":"https://github.com/polarmobile/coffeescript-style-guide","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/polarmobile/coffeescript-style-guide","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polarmobile%2Fcoffeescript-style-guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polarmobile%2Fcoffeescript-style-guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polarmobile%2Fcoffeescript-style-guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polarmobile%2Fcoffeescript-style-guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/polarmobile","download_url":"https://codeload.github.com/polarmobile/coffeescript-style-guide/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/polarmobile%2Fcoffeescript-style-guide/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30544726,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-15T14:38:58.992Z","status":"ssl_error","status_checked_at":"2026-03-15T14:38:29.659Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T02:00:56.302Z","updated_at":"2026-03-15T14:54:43.267Z","avatar_url":"https://github.com/polarmobile.png","language":null,"funding_links":[],"categories":["Programming Languages","CoffeeScript","Platforms","JavaScript","Others"],"sub_categories":["CoffeeScript","Frontend Development"],"readme":"# CoffeeScript Style Guide\n\nThis guide presents a collection of best-practices and coding conventions for the [CoffeeScript][coffeescript] programming language.\n\nThis guide is intended to be community-driven, and contributions are highly encouraged.\n\nPlease note that this is a work-in-progress: there is much more that can be specified, and some of the guidelines that have been specified may not be deemed to be idiomatic by the community (in which case, these offending guidelines will be modified or removed, as appropriate).\n\n## Inspiration\n\nThe details in this guide have been very heavily inspired by several existing style guides and other resources. In particular:\n\n- [PEP-8][pep8]: Style Guide for Python Code\n- Bozhidar Batsov's [Ruby Style Guide][ruby-style-guide]\n- [Google's JavaScript Style Guide][google-js-styleguide]\n- [Common CoffeeScript Idioms][common-coffeescript-idioms]\n- Thomas Reynolds' [CoffeeScript-specific Style Guide][coffeescript-specific-style-guide]\n- Jeremy Ashkenas' [code review][spine-js-code-review] of [Spine][spine-js]\n- The [CoffeeScript FAQ][coffeescript-faq]\n\n## Table of Contents\n\n* [The CoffeeScript Style Guide](#guide)\n    * [Code Layout](#code_layout)\n        * [Tabs or Spaces?](#tabs_or_spaces)\n        * [Maximum Line Length](#maximum_line_length)\n        * [Blank Lines](#blank_lines)\n        * [Trailing Whitespace](#trailing_whitespace)\n        * [Optional Commas](#optional_commas)\n        * [Encoding](#encoding)\n    * [Module Imports](#module_imports)\n    * [Whitespace in Expressions and Statements](#whitespace)\n    * [Comments](#comments)\n        * [Block Comments](#block_comments)\n        * [Inline Comments](#inline_comments)\n    * [Naming Conventions](#naming_conventions)\n    * [Functions](#functions)\n    * [Strings](#strings)\n    * [Conditionals](#conditionals)\n    * [Looping and Comprehensions](#looping_and_comprehensions)\n    * [Extending Native Objects](#extending_native_objects)\n    * [Exceptions](#exceptions)\n    * [Annotations](#annotations)\n    * [Miscellaneous](#miscellaneous)\n\n\u003ca name=\"code_layout\"/\u003e\n## Code layout\n\n\u003ca name=\"tabs_or_spaces\"/\u003e\n### Tabs or Spaces?\n\nUse **spaces only**, with **2 spaces** per indentation level. Never mix tabs and spaces.\n\n\u003ca name=\"maximum_line_length\"/\u003e\n### Maximum Line Length\n\nLimit all lines to a maximum of 79 characters.\n\n\u003ca name=\"blank_lines\"/\u003e\n### Blank Lines\n\nSeparate top-level function and class definitions with a single blank line.\n\nSeparate method definitions inside of a class with a single blank line.\n\nUse a single blank line within the bodies of methods or functions in cases where this improves readability (e.g., for the purpose of delineating logical sections).\n\n\u003ca name=\"trailing_whitespace\"/\u003e\n### Trailing Whitespace\n\nDo not include trailing whitespace on any lines.\n\n\u003ca name=\"optional_commas\"/\u003e\n### Optional Commas\n\nAvoid the use of commas before newlines when properties or elements of an Object or Array are listed on separate lines.\n\n```coffeescript\n# Yes\nfoo = [\n  'some'\n  'string'\n  'values'\n]\nbar:\n  label: 'test'\n  value: 87\n\n# No\nfoo = [\n  'some',\n  'string',\n  'values'\n]\nbar:\n  label: 'test',\n  value: 87\n```\n\n\u003ca name=\"encoding\"/\u003e\n### Encoding\n\nUTF-8 is the preferred source file encoding.\n\n\u003ca name=\"module_imports\"/\u003e\n## Module Imports\n\nIf using a module system (CommonJS Modules, AMD, etc.), `require` statements should be placed on separate lines.\n\n```coffeescript\nrequire 'lib/setup'\nBackbone = require 'backbone'\n```\nThese statements should be grouped in the following order:\n\n1. Standard library imports _(if a standard library exists)_\n2. Third party library imports\n3. Local imports _(imports specific to this application or library)_\n\n\u003ca name=\"whitespace\"/\u003e\n## Whitespace in Expressions and Statements\n\nAvoid extraneous whitespace in the following situations:\n\n- Immediately inside parentheses, brackets or braces\n\n    ```coffeescript\n       ($ 'body') # Yes\n       ( $ 'body' ) # No\n    ```\n\n- Immediately before a comma\n\n    ```coffeescript\n       console.log x, y # Yes\n       console.log x , y # No\n    ```\n\nAdditional recommendations:\n\n- Always surround these binary operators with a **single space** on either side\n\n    - assignment: `=`\n\n        - _Note that this also applies when indicating default parameter value(s) in a function declaration_\n\n           ```coffeescript\n           test: (param = null) -\u003e # Yes\n           test: (param=null) -\u003e # No\n           ```\n\n    - augmented assignment: `+=`, `-=`, etc.\n    - comparisons: `==`, `\u003c`, `\u003e`, `\u003c=`, `\u003e=`, `unless`, etc.\n    - arithmetic operators: `+`, `-`, `*`, `/`, etc.\n\n    - _(Do not use more than one space around these operators)_\n\n        ```coffeescript\n           # Yes\n           x = 1\n           y = 1\n           fooBar = 3\n\n           # No\n           x      = 1\n           y      = 1\n           fooBar = 3\n        ```\n\n\u003ca name=\"comments\"/\u003e\n## Comments\n\nIf modifying code that is described by an existing comment, update the comment such that it accurately reflects the new code. (Ideally, improve the code to obviate the need for the comment, and delete the comment entirely.)\n\nThe first word of the comment should be capitalized, unless the first word is an identifier that begins with a lower-case letter.\n\nIf a comment is short, the period at the end can be omitted.\n\n\u003ca name=\"block_comments\"/\u003e\n### Block Comments\n\nBlock comments apply to the block of code that follows them.\n\nEach line of a block comment starts with a `#` and a single space, and should be indented at the same level of the code that it describes.\n\nParagraphs inside of block comments are separated by a line containing a single `#`.\n\n```coffeescript\n  # This is a block comment. Note that if this were a real block\n  # comment, we would actually be describing the proceeding code.\n  #\n  # This is the second paragraph of the same block comment. Note\n  # that this paragraph was separated from the previous paragraph\n  # by a line containing a single comment character.\n\n  init()\n  start()\n  stop()\n```\n\n\u003ca name=\"inline_comments\"/\u003e\n### Inline Comments\n\nInline comments are placed on the line immediately above the statement that they are describing. If the inline comment is sufficiently short, it can be placed on the same line as the statement (separated by a single space from the end of the statement).\n\nAll inline comments should start with a `#` and a single space.\n\nThe use of inline comments should be limited, because their existence is typically a sign of a code smell.\n\nDo not use inline comments when they state the obvious:\n\n```coffeescript\n  # No\n  x = x + 1 # Increment x\n```\n\nHowever, inline comments can be useful in certain scenarios:\n\n```coffeescript\n  # Yes\n  x = x + 1 # Compensate for border\n```\n\n\u003ca name=\"naming_conventions\"/\u003e\n## Naming Conventions\n\nUse `camelCase` (with a leading lowercase character) to name all variables, methods, and object properties.\n\nUse `CamelCase` (with a leading uppercase character) to name all classes. _(This style is also commonly referred to as `PascalCase`, `CamelCaps`, or `CapWords`, among [other alternatives][camel-case-variations].)_\n\n_(The **official** CoffeeScript convention is camelcase, because this simplifies interoperability with JavaScript. For more on this decision, see [here][coffeescript-issue-425].)_\n\nFor constants, use all uppercase with underscores:\n\n```coffeescript\nCONSTANT_LIKE_THIS\n```\n\nMethods and variables that are intended to be \"private\" should begin with a leading underscore:\n\n```coffeescript\n_privateMethod: -\u003e\n```\n\n\u003ca name=\"functions\"/\u003e\n## Functions\n\n_(These guidelines also apply to the methods of a class.)_\n\nWhen declaring a function that takes arguments, always use a single space after the closing parenthesis of the arguments list:\n\n```coffeescript\nfoo = (arg1, arg2) -\u003e # Yes\nfoo = (arg1, arg2)-\u003e # No\n```\n\nDo not use parentheses when declaring functions that take no arguments:\n\n```coffeescript\nbar = -\u003e # Yes\nbar = () -\u003e # No\n```\n\nIn cases where method calls are being chained and the code does not fit on a single line, each call should be placed on a separate line and indented by one level (i.e., two spaces), with a leading `.`.\n\n```coffeescript\n[1..3]\n  .map((x) -\u003e x * x)\n  .concat([10..12])\n  .filter((x) -\u003e x \u003c 11)\n  .reduce((x, y) -\u003e x + y)\n```\n\nWhen calling functions, choose to omit or include parentheses in such a way that optimizes for readability. Keeping in mind that \"readability\" can be subjective, the following examples demonstrate cases where parentheses have been omitted or included in a manner that the community deems to be optimal:\n\n```coffeescript\nbaz 12\n\nbrush.ellipse x: 10, y: 20 # Braces can also be omitted or included for readability\n\nfoo(4).bar(8)\n\nobj.value(10, 20) / obj.value(20, 10)\n\nprint inspect value\n\nnew Tag(new Value(a, b), new Arg(c))\n```\n\nYou will sometimes see parentheses used to group functions (instead of being used to group function parameters). Examples of using this style (hereafter referred to as the \"function grouping style\"):\n\n```coffeescript\n($ '#selektor').addClass 'klass'\n\n(foo 4).bar 8\n```\n\nThis is in contrast to:\n\n```coffeescript\n$('#selektor').addClass 'klass'\n\nfoo(4).bar 8\n```\n\nIn cases where method calls are being chained, some adopters of this style prefer to use function grouping for the initial call only:\n\n```coffeescript\n($ '#selektor').addClass('klass').hide() # Initial call only\n(($ '#selektor').addClass 'klass').hide() # All calls\n```\n\nThe function grouping style is not recommended. However, **if the function grouping style is adopted for a particular project, be consistent with its usage.**\n\n\u003ca name=\"strings\"/\u003e\n## Strings\n\nUse string interpolation instead of string concatenation:\n\n```coffeescript\n\"this is an #{adjective} string\" # Yes\n\"this is an \" + adjective + \" string\" # No\n```\n\nPrefer single quoted strings (`''`) instead of double quoted (`\"\"`) strings, unless features like string interpolation are being used for the given string.\n\n\u003ca name=\"conditionals\"/\u003e\n## Conditionals\n\nFavor `unless` over `if` for negative conditions.\n\nInstead of using `unless...else`, use `if...else`:\n\n```coffeescript\n  # Yes\n  if true\n    ...\n  else\n    ...\n\n  # No\n  unless false\n    ...\n  else\n    ...\n```\n\nMulti-line if/else clauses should use indentation:\n\n```coffeescript\n  # Yes\n  if true\n    ...\n  else\n    ...\n\n  # No\n  if true then ...\n  else ...\n```\n\n\u003ca name=\"looping_and_comprehensions\"/\u003e\n## Looping and Comprehensions\n\nTake advantage of comprehensions whenever possible:\n\n```coffeescript\n  # Yes\n  result = (item.name for item in array)\n\n  # No\n  results = []\n  for item in array\n    results.push item.name\n```\n\nTo filter:\n\n```coffeescript\nresult = (item for item in array when item.name is \"test\")\n```\n\nTo iterate over the keys and values of objects:\n\n```coffeescript\nobject = one: 1, two: 2\nalert(\"#{key} = #{value}\") for key, value of object\n```\n\n\u003ca name=\"extending_native_objects\"/\u003e\n## Extending Native Objects\n\nDo not modify native objects.\n\nFor example, do not modify `Array.prototype` to introduce `Array#forEach`.\n\n\u003ca name=\"exceptions\"/\u003e\n## Exceptions\n\nDo not suppress exceptions.\n\n\u003ca name=\"annotations\"/\u003e\n## Annotations\n\nUse annotations when necessary to describe a specific action that must be taken against the indicated block of code.\n\nWrite the annotation on the line immediately above the code that the annotation is describing.\n\nThe annotation keyword should be followed by a colon and a space, and a descriptive note.\n\n```coffeescript\n  # FIXME: The client's current state should *not* affect payload processing.\n  resetClientState()\n  processPayload()\n```\n\nIf multiple lines are required by the description, indent subsequent lines with two spaces:\n\n```coffeescript\n  # TODO: Ensure that the value returned by this call falls within a certain\n  #   range, or throw an exception.\n  analyze()\n```\n\nAnnotation types:\n\n- `TODO`: describe missing functionality that should be added at a later date\n- `FIXME`: describe broken code that must be fixed\n- `OPTIMIZE`: describe code that is inefficient and may become a bottleneck\n- `HACK`: describe the use of a questionable (or ingenious) coding practice\n- `REVIEW`: describe code that should be reviewed to confirm implementation\n\nIf a custom annotation is required, the annotation should be documented in the project's README.\n\n\u003ca name=\"miscellaneous\"/\u003e\n## Miscellaneous\n\n`and` is preferred over `\u0026\u0026`.\n\n`or` is preferred over `||`.\n\n`is` is preferred over `==`.\n\n`isnt` is preferred over `!=`.\n\n`not` is preferred over `!`.\n\n`or=` should be used when possible:\n\n```coffeescript\ntemp or= {} # Yes\ntemp = temp || {} # No\n```\n\nPrefer shorthand notation (`::`) for accessing an object's prototype:\n\n```coffeescript\nArray::slice # Yes\nArray.prototype.slice # No\n```\n\nPrefer `@property` over `this.property`.\n\n```coffeescript\nreturn @property # Yes\nreturn this.property # No\n```\n\nHowever, avoid the use of **standalone** `@`:\n\n```coffeescript\nreturn this # Yes\nreturn @ # No\n```\n\nAvoid `return` where not required, unless the explicit return increases clarity.\n\nUse splats (`...`) when working with functions that accept variable numbers of arguments:\n\n```coffeescript\nconsole.log args... # Yes\n\n(a, b, c, rest...) -\u003e # Yes\n```\n\n[coffeescript]: http://jashkenas.github.com/coffee-script/\n[coffeescript-issue-425]: https://github.com/jashkenas/coffee-script/issues/425\n[spine-js]: http://spinejs.com/\n[spine-js-code-review]: https://gist.github.com/1005723\n[pep8]: http://www.python.org/dev/peps/pep-0008/\n[ruby-style-guide]: https://github.com/bbatsov/ruby-style-guide\n[google-js-styleguide]: http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml\n[common-coffeescript-idioms]: http://arcturo.github.com/library/coffeescript/04_idioms.html\n[coffeescript-specific-style-guide]: http://awardwinningfjords.com/2011/05/13/coffeescript-specific-style-guide.html\n[coffeescript-faq]: https://github.com/jashkenas/coffee-script/wiki/FAQ\n[camel-case-variations]: http://en.wikipedia.org/wiki/CamelCase#Variations_and_synonyms\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolarmobile%2Fcoffeescript-style-guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolarmobile%2Fcoffeescript-style-guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolarmobile%2Fcoffeescript-style-guide/lists"}