[CoffeeScript]编码风格指南

??

这份指南阐述了一些 CoffeeScript 的最佳实践和编码惯例。

这份指南是社群驱动的，非常鼓励大家来贡献内容。

请注意这还是一份正在完善的指南：仍有很多地方可以改进，有些已制定的准则也不一定是社区惯用的（基于此，在适当的情况下，这些有待斟酌的准则将有可能被修改或删除。）

灵感

本指南中的很多细节受到了几份现有的风格指南和其他资源的启发。特别是：

代码布局（Code Layout）

Tab 还是 空格？（Tabs or Spaces?）

只用 空格，每级缩进均为 2 个空格。切勿混用 Tab 和空格。

最大行宽（Maximum Line Length）

限制每行最多 79 个字符。

空行（Blank Lines）

  1. 顶级函数和类的定义用一个空行分开。
  2. 类内部的函数定义也用一个空行分开。
  3. 对于每个函数体内，只在为了提高可读性的情况下才使用一个空行（例如：为了达到划分逻辑的目的）。

结尾空白（Trailing Whitespace）

不要在任何一行保留行尾空白。

可选的逗号（Optional Commas）

当对象（或数组）的属性（或元素）作为单独一行列出时，避免在换行符前使用逗号。如下：


1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

# 好

foo = [

  ‘some‘

  ‘string‘

  ‘values‘

]

bar:

  label: ‘test‘

  value: 87

# 差

foo = [

  ‘some‘,

  ‘string‘,

  ‘values‘

]

bar:

  label: ‘test‘,

  value: 87

编码（Encoding）

UTF-8 是首选的源文件编码。

模块导入（Module Imports）

如果需要导入模块 (CommonJS 模块，AMD，等等.), require 语句应该单独作为一行。如下：


1

2

require ‘lib/setup‘

Backbone = require ‘backbone‘

这些语句应该按以下顺序去分组：

  1. 标准库的导入 （如果标准库存在）
  2. 第三方库的导入
  3. 本地导入 （导入这个应用程序的或库的具体依赖）

表达式和语句中的空白（Whitespace in Expressions and Statements）

下列情况应该避免多余的空格：

  • 紧贴着圆括号、方括号和大括号内部

1

2

($ ‘body‘) # 好

 ( $ ‘body‘ ) # 差

紧贴在逗号前


1

2

console.log x, y # 好

console.log x , y # 差

额外建议：

  • 在下列二元操作符的左右两边都保留 一个空格

    • 赋值运算符: =
      注意：这同样适用于函数定义中的默认参数

1

2

test: (param = null) -> # 好

test: (param=null) -> # 差
  • 自增运算符: +=, -=, 等等。
  • 比较运算符: ==, <, >, <=, >=, unless, 等等。
  • 算术运算符: +, -, *, /, 等等。
  • （这些操作符两边的空格不要多于一个）

1

2

3

4

5

6

7

8

9

# 好

  x = 1

  y = 1

  fooBar = 3

  # 差

  x      = 1

  y      = 1

  fooBar = 3

注释（Comments）

如果你修改了一段已有注释说明的代码，则也要更新它对应的注释。（理想状态是，重构这段代码直到它不需要注释说明，然后再把之前的注释全删掉。）

注释的首字母要大写，除非第一个单词是以小写字母开头的标识符。

如果注释很短，可以省略末尾的句号。

块注释（Block Comments）

注释块通常应用于尾随其后的一段代码。

每一行注释都以 # 加一个空格开头，而且和被注释的代码有相同的缩进层次。

注释块内的段落以仅含单个 # 的行分割。


1

2

3

4

5

6

7

8

9

# 这是一个块注释。请注意假如这是一段块注释，

 # 则它描述的就应该是接下来的这段代码。

 #

 # 这是块注释的第二段。

 # 请注意这段是由上一行带有 # 号的空行分开的。（P.S. 最好用英文写注释）

 init()

 start()

 stop()

行内注释（Inline Comments）

行内注释紧贴在被描述的代码的上一行，如果行内注释足够短，则可以处在同一行行尾（由一个空格隔开）。

所有行内注释都以 # 加一个空格开头。

应该限制行内注释的使用，因为它们的存在通常是一个代码异味的标志。

不要给显而易见的情况作行内注释：


1

2

# 差

x = x + 1 # x 自增

然而，行内注释在某些情况下是有用的：


1

2

# 好

x = x + 1 # 边界补足

命名规范（Naming Conventions）

使用 小驼峰命名法 （第一个词的首字母小写，后面每个词的首字母大写）来命名所有的变量、方法和对象属性。

使用 大驼峰命名法 （第一个词的首字母，以及后面每个词的首字母都大写）来命名所有的类 （在其他类似的命名法中，这种风格通常也被称为 帕斯卡命名法（PascalCase）、 大写驼峰命名法（CamelCaps） 或 首字母大写命名法（CapWords）。）

（CoffeeScript 官方 约定是用驼峰命名法，因为这可以简化与 JavaScript 的相互转化，想了解更多，请看这里.)

对于常量，单词全部大写，用下划线隔开即可：


1

CONSTANT_LIKE_THIS

私有函数和私有变量都应该在前面加一个下划线：


1

_privateMethod: ->

函数（Functions）

（以下这些准则同样适用于类中的方法。）

当声明一个带参函数时，应在参数列表的右圆括号后空出一个空格：


1

2

foo = (arg1, arg2) -> # 好

foo = (arg1, arg2)-> # 差

无参函数不要用圆括号：


1

2

bar = -> # 好

bar = () -> # 差

当函数链式调用，却在一行放不下时，则把每个函数调用都另起一行，且都缩进一级（即在 . 前加两个空格）。


1

2

3

4

5

[1..3]

  .map((x) -> x * x)

  .concat([10..12])

  .filter((x) -> x < 11)

  .reduce((x, y) -> x + y)

当调用函数时，我们应该为了提高可读性而去掉圆括号。请记住，「可读性」是我们主观臆断的。只有类似下面几个例子的情况才被社区认为是最佳的：


1

2

3

4

5

6

7

8

9

10

11

baz 12

brush.ellipse x: 10, y: 20 # 大括号在适当的时候也可以去掉

foo(4).bar(8)

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

print inspect value

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

有时候你会发现圆括号用来包裹的是函数体（而不是函数的参数）。请看下面的例子（以下简称为「函数体风格」）：


1

2

3

($ ‘#selektor‘).addClass ‘klass‘

(foo 4).bar 8

这段代码会编译为：


1

2

3

$(‘#selektor‘).addClass ‘klass‘

foo(4).bar 8

一些习惯链式调用的人会巧用「函数体风格」进行单独初始化：


1

2

($ ‘#selektor‘).addClass(‘klass‘).hide() # 单独初始化调用

(($ ‘#selektor‘).addClass ‘klass‘).hide() # 全部调用

「函数体风格」并不得到推荐。但是， 当它适应一些特殊的项目需求时，还是得用它。

字符串（Strings）

用字符串插值代替字符串连接符：


1

2

"this is an #{adjective} string" # 好

"this is an " + adjective + " string" # 差

最好用单引号 (‘‘) 而不是双引号 ("") 。除非是插入到另一段现有的字符串中（类似字符串插值）

条件判断（Conditionals）

用 unless 来代替 if 的否定情况。

不要用 unless...else， 而用 if...else:


1

2

3

4

5

6

7

8

9

10

11

# 好

 if true

   ...

 else

   ...

 # 差

 unless false

   ...

 else

   ...

多行的 if/else 语句应该缩进：


1

2

3

4

5

6

7

8

9

# 好

 if true

   ...

 else

   ...

 # 差

 if true then ...

 else ...

循环和列表解析（Looping and Comprehensions）

尽可能的使用列表解析：


1

2

3

4

5

6

7

# 好

 result = (item.name for item in array)

 # 差

 results = []

 for item in array

   results.push item.name

还可以过滤结果：


1

result = (item for item in array when item.name is "test")

遍历对象的键值：


1

2

object = one: 1, two: 2

alert("#{key} = #{value}") for key, value of object

扩展本地对象（Extending Native Objects）

不要修改本地对象。

比如，不要给 Array.prototype 引入 Array#forEach 。

异常（Exceptions）

不要抑制异常抛出。

注解（Annotations）

必要的时候应该写注解，来指明接下来的代码块具体将干什么。

注解应紧贴在被描述代码的上一行。

注解关键字后面应该跟一个冒号加一个空格，加一个描述性的注释。


1

2

3

# FIXME: The client‘s current state should *not* affect payload processing.

resetClientState()

processPayload()

如果注解不止一行，则下一行缩进两个空格。


1

2

3

# TODO: Ensure that the value returned by this call falls within a certain

#   range, or throw an exception.

analyze()

注解有以下几类：

  • TODO: 描述缺失的功能，以便日后加入
  • FIXME: 描述需要修复的代码
  • OPTIMIZE: 描述性能低下，或难以优化的代码
  • HACK: 描述一段值得质疑（或很巧妙）的代码
  • REVIEW: 描述需要确认其编码意图是否正确的代码

如果你必须自定义一个新的注解类型，则应该把这个注解类型记录在项目的 README 里面。

其他（Miscellaneous）

and 更优于 &&.

or 更优于 ||.

is 更优于 ==.

not 更优于 !.

or= 应在可能的情况下使用：


1

2

temp or= {} # 好

temp = temp || {} # 差

最好用 (::) 访问对象的原型：


1

2

Array::slice # 好

Array.prototype.slice # 差

最好用 @property 而不是 this.property.


1

2

return @property # 好

return this.property # 差

但是，避免使用 单独的 @:


1

2

return this # 好

return @ # 差

没有返回值的时候避免使用 return ，其他情况则需要显示 return 。

当函数需要接收可变数量的参数时，使用 splats (...)。


1

2

3

console.log args... # 好

(a, b, c, rest...) -> # 好
时间： 2024-08-10 15:10:26

[CoffeeScript]编码风格指南的相关文章

来自 Google 的 R 语言编码风格指南

本文转自Xiao Nan的博客 R语言是一门主要用于统计计算和绘图的高级编程语言. 这份 R 语言编码风格指南旨在让我们的 R 代码更容易阅读.分享和检查. 以下规则系与 Google 的 R 用户群体协同设计而成. 概要: R编码风格约定 文件命名: 以 .R (大写) 结尾 标识符命名: variable.name, FunctionName, kConstantName 单行长度: 不超过 80 个字符 缩进: 两个空格, 不使用制表符 空白 花括号: 前括号不折行写, 后括号独占一行 赋

JavaScript 编码风格指南

A.1  缩进 // 4个空格的层级缩进 if (true) { doSomething(); } A.2  行的长度 // 每行限于80个字符,超出则在运算符后换行,缩进2个层级(8个空格) doSomething(argument1, argument2, argument3, argument4, argument5); A.3  原始值 // 字符串使用双引号及长字符串的链接 var name = "Nicholas", longStr = "this is a lo

R 语言编码风格指南

R 语言是一门主要用于统计计算和绘图的高级编程语言.这份 R 语言编码风格指南旨在让我们的 R代码更容易阅读.分享和检查.以下规则系与 Google 的 R 用户群体协同设计而成. 概要: R编码风格约定 文件命名: 以 .R (大写) 结尾 标识符命名: variable.name, FunctionName, kConstantName 单行长度: 不超过 80 个字符 缩进: 两个空格, 不使用制表符 空白 花括号: 前括号不折行写, 后括号独占一行 赋值符号: 使用 <-, 而非 = 分

【翻译】Ext JS——高效的编码风格指南

原文:ExtJS - Efficient coding style guide 作者:Raja 切勿使用"new"关键字:在Ext JS中,使用"new"关键字来创建一个组件或类的实例是一种错误的做法,因为这没有遵循组件的生命周期.应该使用Ext.create方法来创建对象,例如: 错误: var obj = new Ext.panel.Panel(); 正确: var obj = Ext.create('Ext.panel.Panel'); 初始化直接量:不要直接

【翻译】EXTJS 编码风格指南与实例

原文:EXTJS Code Style Guide with examples Ext JS风格指南: 熟知的且易于学习 快速开发,易于调试,轻松部署 组织良好.可扩展和可维护 Ext JS应用程序的命名约定: 1.类 类名应使用驼峰命名(CamelCased).不要使用下划线,或其他连接字符.如:MyCustomClass 不是通过Sencha分发的类,永远不要使用Ext作为顶层命名空间.在类名中,应至少使用一次点号来划分命名空间.如TopLevelNamespace.MyClassName

(转)PEP 8——Python编码风格指南

PEP 8--Python编码风格指南标签(空格分隔): Python PEP8 编码规范原文:https://lizhe2004.gitbooks.io/code-style-guideline-cn/content/python/python-pep8.html https://python.freelycode.com/contribution/detail/47------PEP8中文版 -- Python编码风格指南(上,中,下) https://python.freelycode.c

PHP编码风格指南 (PHP-FIG PSR-2)

本指南是 PSR-1 基本编码标准 的扩展. 本指罗列了通用的PHP代码格式规则和建议,意在减少不同作者的编码风格差异带来的认知障碍. 这里的风格约定衍生自若干成员项目.指南作者们在多个项目中协作,推动了这些指导条款落地. 指南的关键在于共享,而不是规则本身. 文中涉及的关键词 "MUST 必须", "MUST NOT 必须不", "REQUIRED 必需", "SHALL 会", "SHALL NOT 不会&quo

JavaScript编码风格指南(中文版)

前言:程序语言的编码风格对于一个长期维护的软件非常重要,特别是在团队协作中.如果一个团队使用统一规范的编码分风格,可以提高团队的协作水平和工作效率.编程风格指南的核心是基本的格式化规则,这些规则决定了如何编写高水准的代码.本指南来自于<编写可维护的JavaScript>这本书,基于"Java语言编码规范"和Crockford的JavaScript编程规范,还有Nicbolas的一些个人经验和喜好.写作本文旨在加深自己印象,也为了更多人的了解到JS编码风格,提高自己的编码质量

《编写可维护的 Javascript》读书笔记（附录 A 部分）：Javascript 编码风格指南（1）原始值

记录一下比较有用的编码规范(该指南是基于 Java 语言编码规范和 Javascript 编程规范,同时结合作者 Nicholos Zakas 的个人经验和喜好). 一些关于格式(包括缩进.行的长度.运算符间距.括号间距.对象直接量.注释.单行注释.多行注释等类似的规范)的规范这里不做记录. A.3 原始值 // 好的写法 var name = "Nicholos"; // 不好的写法:单引号 var name = 'Nicholos'; // 不好的写法:字符串结束之前换行 var