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 类文档,可以让开发者在写代码时更专注于写代码,在写文档时则更专注于写文档。让工作解耦,更专注。

相关讨论

1

1

1

1

1

1

1

1

1

1

JavaScript 注释规范的更多相关文章

  1. javascript注释规范

    注释在代码编写过程中的重要性,写代码超过半年的就能深深的体会到.没有注释的代码都不是好代码.为了别人学习,同时为了自己以后对代码进行'升级',看看js/javascript代码注释规范与示例.来自:h ...

  2. sublime注释插件与javascript注释规范

    前言 代码中注释是不可少的,即使是自己写的代码,过了一段时间之后再重看,如果没有注释记录的话,可能会想不到当初是这样实现的,尤其是在业务逻辑比较复杂的项目,注释变得尤为重要.怎么优雅的写有用的注释呢? ...

  3. Sublime Text3 插件:DocBlockr与javascript注释规范

    原:http://www.ithao123.cn/content-719950.html 1.引子 在写代码的时候,尤其是写脚本,最需要注释了.目前脚本.样式的注释格式都有一个已经成文的约定规范(这些 ...

  4. 【JavaScript 开发规范】

    Javascript 最佳实践http://sofish.de/1171http://sofish.de/1181 总是使用 ‘var’ √ 特性检测而非浏览器检测 √ 使用方括号记法 √ 使用&qu ...

  5. JavaScript语法规范

    推荐的JavaScript编码规范 阅读 247 评论 0 喜欢 0 作为前端开发人员,我相信每一个人都或多或少的用到原生的JavaScript,也正是因为用的人多,导致编码风格也是多种多样的,而不规 ...

  6. JavaScript编码规范指南

    前言 本文摘自Google JavaScript编码规范指南,截取了其中比较容易理解与遵循的点作为团队的JavaScript编码规范. JavaScript 语言规范 变量 声明变量必须加上 var  ...

  7. JavaScript编码规范[百度]

    JavaScript编码规范 1 前言   2 代码风格   2.1 文件   2.2 结构   2.2.1 缩进   2.2.2 空格   2.2.3 换行   2.2.4 语句   2.3 命名 ...

  8. JavaScript 代码规范

    所有的 JavaScript 项目适用同一种规范. JavaScript 代码规范 代码规范通常包括以下几个方面: 变量和函数的命名规则 空格,缩进,注释的使用规则. 其他常用规范-- 规范的代码可以 ...

  9. JavaScript 编码规范(中文/Airbnb公司版)

    Airbnb 是一家位于美国旧金山的公司,本文是其内部的 JavaScript编码规范,写得比较全面,在 Github 上有 16,686 + Star,3,080 + fork,前端开发人员可参考. ...

随机推荐

  1. history附上时间戳,history命令_Linux history命令:查看和执行历史命令

    起因是这样的,一台机器客户反馈连接不上,说没有任何操作.好吧,排查吧. 1.第一步先看网络是否通: 从图中可以看到一开始是一直不通的.然后就通了,问了客户有没操作重启什么的结果说没有任何操作,还让给个 ...

  2. Eclipse在线安装FatJar插件失败解决方案

    在线安装fatjar(URL:http://kurucz-grafika.de/fatjar) 快要安装完的时候报错如下: 找了很久解决方法,终于有了下文:很是粗乎意料呃,下载一个eclipse2.0 ...

  3. 计算机网络安全 —— C# 使用谷歌身份验证器(Google Authenticator)(五)

    一.Google Authenticator 基本概念  Google Authenticator是谷歌推出的一款动态口令工具,旨在解决大家Google账户遭到恶意攻击的问题,在手机端生成动态口令后, ...

  4. missing required library sqlite.dll最终解决办法

    missing required library sqlite.dll最终解决办法 昨天电脑还是好的,今天早晨打开navicat连接Mysql无缘无故报错"missing required ...

  5. Bitter.Core系列七:Bitter ORM NETCORE ORM 全网最粗暴简单易用高性能的 NETCore ORM 示例 更新删除插入

    Bitter Orm 在操作数据库增删改的时候,支持模型驱动和直接执行裸SQL 操作,示例代码如下: 一:模型驱动(增删改) /// <summary> /// 插入,删除,更新示例(模型 ...

  6. 数据库内核——基于HLC的分布式事务实现深度剖析

    DTCC 2019 | 深度解码阿里数据库实现 数据库内核--基于HLC的分布式事务实现深度剖析-阿里云开发者社区 https://developer.aliyun.com/article/70355 ...

  7. 指令集架构 x86-64 x86架构的64位拓展,向后兼容于16位及32位的x86架构

    https://zh.wikipedia.org/wiki/X86 x86泛指一系列英特尔公司用于开发处理器的指令集架构,这类处理器最早为1978年面市的"Intel 8086"C ...

  8. mysql高级day3

    Mysql高级-day03 1. 应用优化 前面章节,我们介绍了很多数据库的优化措施.但是在实际生产环境中,由于数据库本身的性能局限,就必须要对前台的应用进行一些优化,来降低数据库的访问压力. 1.1 ...

  9. MyBatis逆向工程生成dao层增删改查方法解释使用(转载)

    int countByExample(BUserExample example); //根据条件查询数量 /** * 示例 * public int countByExample() { * BUse ...

  10. [NC13331]城市网络

    传送门 题意: 思路: 对于每组查询,我们直接从$u$往上搜到$v$,复杂度$O(nq)$,显然不可取(不过这题开始的数据很弱,暴力就过了) #include<bits/stdc++.h> ...