来自支付宝的《JavaScript 注释规范》 ## 总原则

  1. As short as possible(如无必要,勿增注释)。尽量提高代码本身的清晰性、可读性。
  2. As long as necessary(如有必要,尽量详尽)。合理的注释、空行排版等,可以让代码更易阅读、更具美感。

总之,注释的目的是:提高代码的可读性,从而提高代码的可维护性。

什么时候需要添加注释

  1. 某段代码的写法,需要注释说明 why 时:
// Using loop is more efficient than `rest = slice.call(arguments, 1)`.
for (i = 1, len = arguments.length; i < len; i++) {
    rest[i - 1] = arguments[i];
}
  1. 添加上注释,能让代码结构更清晰时:
init: function(selector, context, rootjQuery) {
    var match, elem, ret, doc;

    // Handle $(""), $(null), or $(undefined)
    if ( !selector ) {
        ...
    }

    // Handle $(DOMElement)
    if ( selector.nodeType ) {
        ...
    }

    // The body element only exists once, optimize finding it
    if ( typeof selector === "string" ) {
        ...
     }
}
  1. 有借鉴第三方代码,需要说明时:
// Inspired by https://github.com/jquery/jquery/blob/master/src/core.js
function ready() {
    ...
}

文件起始处的约定

每个源码文件的开头,保留为空:

define(function(require, exports, module) {
    // 源代码
});

注意点:

  1. 文件头不添加作者信息,是因为更推崇团队和社区参与。author 和 contributors 信息,在 GitHub 上可以清晰看出来。(注意:该条规范,仅适用于 Arale 组件。对于业务代码,请添加上作者信息,以便在出问题时,快速找到负责人。)
  2. 文件最后空一行,可以保证在 combo 合并后,源码的层次清晰。

注释书写规范

  1. 源码中的注释,推荐用英文。
  2. 含有中文时,标点符号用中文全角。
  3. 中英文夹杂时,英文与中文之间要用一个空格分开。
  4. 注释标识符与注释内容要用一个空格分开:// 注释/* 注释 */

JSDoc 注释

  • 不推荐 JSDoc 式注释,推荐 Backbone 风格的注释。
  • API 请通过 README 等文档表达清楚。
  • 不写 JSDoc 类文档,可以让开发者在写代码时更专注于写代码,在写文档时则更专注于写文档。让工作解耦,更专注。

相关链接

来自支付宝的《JavaScript 编码风格》

下面是一些常用注意点:

编码

统一用 utf-8

长度

长度不超过 80 个字符。别小看这一条规则,如果严格去遵循,你会发现代码变清晰了。而且,你一定能做到的。

参考:

  1. pep8 为 79 个字符
  2. npm 为 80 个字符
  3. google 为 80 个字符

缩进

缩进使用 2个 或 4个 空格,组件内保持统一,不混用。禁用 tab。

参考:

  1. npm 为 2 空格
  2. pep8 为 4 空格
  3. google 为 2 空格( gjslint 没规定)
  4. 大部分前端工程师习惯 4 空格

Vim 设置 tab 为 4 空格:

set tabstop=4
set shiftwidth=4
set expandtab

花括号

花括号不换行

if (foo) {
}

if (foo)
{
}

不允许一行判断,一律换行

if (foo) return;

命名约定

  1. 常量 UPPERCASE_WORD
  2. 变量 camelName
  3. 类名 CamelName

空格

操作符之间需要空格

var x = y + z

var x=y+z

只空一格

{
    a: 'short',
    looooongname: 'long'
}

{
    a           : 'short',
    looooongname: 'long'
}

逗号与换行

建议用自然人的处理方法

{
   a: 'a',
   b: 'b',
   c: 'c'
}

不建议使用 npm 风格的逗号与换行,即

{
   a: 'a'
  ,b: 'b'
  ,c: 'c'
}

变量声明

首先,变量在使用前必须声明

对于单 var 模式和多 var 模式,不做强行约定,但同一个文件里,风格必须一致。

相关链接

短按电源键 (Power)

去搜索 OS X 怎么锁屏, 很多地方会提到短按电源键, 可惜这个也是睡眠, 问题同上

设置触发角进入屏保

不少教程也是教的这个, 大致流程如下

  1. 进入 系统偏好设置
  2. 在 安全性与隐私 设定页, 通用 标签卡里将 进入睡眠或开始屏幕保护程序后要求输入密码 的时间改成 立即
  3. 在 桌面与屏幕保护程序 设定页, 屏幕保护程序 标签卡右下角设定 触发角, 行为选 将显示器置入睡眠状态

注:

  • 第 2 步也可以在 Mission Control 设定页的左下角找到 触发角 的设置
  • 第 3 步的触发行为也可以选 启动屏幕保护程序, 但是这样就不是我想要的完全黑屏那种锁法

真正的快捷键

在 http://apple.stackexchange.com/questions/28164/keyboard-shortcut-to-sleep-a-mac 这个帖里比较完整的提到了各种快捷键 (老键盘上把 Power 换成 Eject 键):

  • Ctrl+Shift+Power: 关闭屏幕
  • Cmd+Opt+Power: 睡眠 (sleep)
  • Cmd+Ctrl+Power: 重启 (restart)
  • Cmd+Ctrl+Opt+Power: 关机 (shutdown)

通过 Ctrl+Shift+Power 终于搞定了怎么键盘快速锁屏, 同时在“系统偏好设置-安全性与隐私”中,选择“进入睡眠或屏保后要求立即输入密码”,这样可以实现快速锁定屏幕。

Here be a sample post with a custom background image. To utilize this “feature” just add the following YAML to a post’s front matter.

image:
  background: filename.png

This little bit of YAML makes the assumption that your background image asset is in the /images folder. If you place it somewhere else or are hotlinking from the web, just include the full http(s):// URL. Either way you should have a background image that is tiled.

If you want to set a background image for the entire site just add background: filename.png to your _config.yml and BOOM — background images on every page!

Background images from Subtle Patterns (Subtle Patterns) / CC BY-SA 3.0

Syntax highlighting is a feature that displays source code, in different colors and fonts according to the category of terms. This feature facilitates writing in a structured language such as a programming language or a markup language as both structures and syntax errors are visually distinct. Highlighting does not affect the meaning of the text itself; it is intended only for human readers.

Pygments Code Blocks

To modify styling and highlight colors edit /assets/less/pygments.less and compile main.less with your favorite preprocessor. Or edit main.css if that’s your thing, the classes you want to modify all begin with .highlight.

#container {
    float: left;
    margin: 0 -240px 0 0;
    width: 100%;
}

Line numbering enabled:

1 <nav class="pagination" role="navigation">
2     {% if page.previous %}
3         <a href="{{ site.url }}{{ page.previous.url }}" class="btn" title="{{ page.previous.title }}">Previous article</a>
4     {% endif %}
5     {% if page.next %}
6         <a href="{{ site.url }}{{ page.next.url }}" class="btn" title="{{ page.next.title }}">Next article</a>
7     {% endif %}
8 </nav><!-- /.pagination -->
module Jekyll
  class TagIndex < Page
    def initialize(site, base, dir, tag)
      @site = site
      @base = base
      @dir = dir
      @name = 'index.html'
      self.process(@name)
      self.read_yaml(File.join(base, '_layouts'), 'tag_index.html')
      self.data['tag'] = tag
      tag_title_prefix = site.config['tag_title_prefix'] || 'Tagged: '
      tag_title_suffix = site.config['tag_title_suffix'] || '&#8211;'
      self.data['title'] = "#{tag_title_prefix}#{tag}"
      self.data['description'] = "An archive of posts tagged #{tag}."
    end
  end
end

Standard Code Block

<nav class="pagination" role="navigation">
    {% if page.previous %}
        <a href="{{ site.url }}{{ page.previous.url }}" class="btn" title="{{ page.previous.title }}">Previous article</a>
    {% endif %}
    {% if page.next %}
        <a href="{{ site.url }}{{ page.next.url }}" class="btn" title="{{ page.next.title }}">Next article</a>
    {% endif %}
</nav><!-- /.pagination -->

Fenced Code Blocks

To modify styling and highlight colors edit /assets/less/coderay.less and compile main.less with your favorite preprocessor. Or edit main.css if that’s your thing, the classes you want to modify all begin with .coderay. Line numbers and a few other things can be modified in _config.yml under coderay.

#container {
    float: left;
    margin: 0 -240px 0 0;
    width: 100%;
}
<nav class="pagination" role="navigation">
    {% if page.previous %}
        <a href="{{ site.url }}{{ page.previous.url }}" class="btn" title="{{ page.previous.title }}">Previous article</a>
    {% endif %}
    {% if page.next %}
        <a href="{{ site.url }}{{ page.next.url }}" class="btn" title="{{ page.next.title }}">Next article</a>
    {% endif %}
</nav><!-- /.pagination -->
module Jekyll
  class TagIndex < Page
    def initialize(site, base, dir, tag)
      @site = site
      @base = base
      @dir = dir
      @name = 'index.html'
      self.process(@name)
      self.read_yaml(File.join(base, '_layouts'), 'tag_index.html')
      self.data['tag'] = tag
      tag_title_prefix = site.config['tag_title_prefix'] || 'Tagged: '
      tag_title_suffix = site.config['tag_title_suffix'] || '&#8211;'
      self.data['title'] = "#{tag_title_prefix}#{tag}"
      self.data['description'] = "An archive of posts tagged #{tag}."
    end
  end
end