JavaScript 注释规范
JavaScript 注释规范
总原则
- As short as possible(如无必要,勿增注释)。尽量提高代码本身的清晰性、可读性。
- As long as necessary(如有必要,尽量详尽)。合理的注释、空行排版等,可以让代码更易阅读、更具美感。
总之,注释的目的是:提高代码的可读性,从而提高代码的可维护性。
什么时候需要添加注释
- 某段代码的写法,需要注释说明 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];
}
- 添加上注释,能让代码结构更清晰时:
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" ) {
...
}
}
- 有借鉴第三方代码,需要说明时:
// Inspired by https://github.com/jquery/jquery/blob/master/src/core.js
function ready() {
...
}文件起始处的约定
每个源码文件的开头,保留为空:
define(function(require, exports, module) {
// 源代码
});注意点:
- 文件头不添加作者信息,是因为更推崇团队和社区参与。author 和 contributors 信息,在 GitHub 上可以清晰看出来。(注意:该条规范,仅适用于 Arale 组件。对于业务代码,请添加上作者信息,以便在出问题时,快速找到负责人。)
- 文件最后空一行,可以保证在 combo 合并后,源码的层次清晰。
注释书写规范
- 源码中的注释,推荐用英文。
- 含有中文时,标点符号用中文全角。
- 中英文夹杂时,英文与中文之间要用一个空格分开。
- 注释标识符与注释内容要用一个空格分开:
// 注释
与/* 注释 */
。JSDoc 注释
- 不推荐 JSDoc 式注释,推荐 Backbone 风格的注释。
- API 请通过 README 等文档表达清楚。
- 不写 JSDoc 类文档,可以让开发者在写代码时更专注于写代码,在写文档时则更专注于写文档。让工作解耦,更专注。
相关讨论
1
1
1
1
1
1
1
1
1
1
JavaScript 注释规范的更多相关文章
- javascript注释规范
注释在代码编写过程中的重要性,写代码超过半年的就能深深的体会到.没有注释的代码都不是好代码.为了别人学习,同时为了自己以后对代码进行'升级',看看js/javascript代码注释规范与示例.来自:h ...
- sublime注释插件与javascript注释规范
前言 代码中注释是不可少的,即使是自己写的代码,过了一段时间之后再重看,如果没有注释记录的话,可能会想不到当初是这样实现的,尤其是在业务逻辑比较复杂的项目,注释变得尤为重要.怎么优雅的写有用的注释呢? ...
- Sublime Text3 插件:DocBlockr与javascript注释规范
原:http://www.ithao123.cn/content-719950.html 1.引子 在写代码的时候,尤其是写脚本,最需要注释了.目前脚本.样式的注释格式都有一个已经成文的约定规范(这些 ...
- 【JavaScript 开发规范】
Javascript 最佳实践http://sofish.de/1171http://sofish.de/1181 总是使用 ‘var’ √ 特性检测而非浏览器检测 √ 使用方括号记法 √ 使用&qu ...
- JavaScript语法规范
推荐的JavaScript编码规范 阅读 247 评论 0 喜欢 0 作为前端开发人员,我相信每一个人都或多或少的用到原生的JavaScript,也正是因为用的人多,导致编码风格也是多种多样的,而不规 ...
- JavaScript编码规范指南
前言 本文摘自Google JavaScript编码规范指南,截取了其中比较容易理解与遵循的点作为团队的JavaScript编码规范. JavaScript 语言规范 变量 声明变量必须加上 var ...
- JavaScript编码规范[百度]
JavaScript编码规范 1 前言 2 代码风格 2.1 文件 2.2 结构 2.2.1 缩进 2.2.2 空格 2.2.3 换行 2.2.4 语句 2.3 命名 ...
- JavaScript 代码规范
所有的 JavaScript 项目适用同一种规范. JavaScript 代码规范 代码规范通常包括以下几个方面: 变量和函数的命名规则 空格,缩进,注释的使用规则. 其他常用规范-- 规范的代码可以 ...
- JavaScript 编码规范(中文/Airbnb公司版)
Airbnb 是一家位于美国旧金山的公司,本文是其内部的 JavaScript编码规范,写得比较全面,在 Github 上有 16,686 + Star,3,080 + fork,前端开发人员可参考. ...
随机推荐
- 大数据谢列3:Hdfs的HA实现
在之前的文章:大数据系列:一文初识Hdfs , 大数据系列2:Hdfs的读写操作 中Hdfs的组成.读写有简单的介绍. 在里面介绍Secondary NameNode和Hdfs读写的流程. 并且在文章 ...
- jmeter的线程数,并发用户数,TPS,RPS 关系解说
背景 在做性能测试的时候,传统方式都是用并发虚拟用户数来衡量系统的性能(站在客户端视角),一般适用于一些网页站点例如首页.H5的压测:而RPS(Requests per second)模式主要是为了方 ...
- promise有几种状态,什么时候会进入catch
三个状态:pending.fulfilled.reject两个过程:padding -> fulfilled.padding -> rejected当pending为rejectd时,会进 ...
- Spring常见问题总结
1. 什么是 Spring 框架? Spring 是一种轻量级开发框架,旨在提高开发人员的开发效率以及系统的可维护性.Spring 官网:https://spring.io/. 我们一般说 Sprin ...
- Excel 快速填充:填充柄+数据验证
鼠标左键拖拽填充或者双击填充 右键拖拽填充: 可以填充等比数列.工作日等等 数据验证: 通过下拉箭头快速选择数据: 选择单元格区域-[数据]-[数据验证]-序列 数据科学交流群,群号:18915878 ...
- Java——反射机制
反射概念: Java反射是Java被视为动态(或准动态)语言的一个关键性质.这个机制允许程序在运行时透过Reflection APIs取得任何一个已知名称的class的内部信息,包括其modifier ...
- cassandra权威指南读书笔记--Cassandra架构(3)
分阶段事件驱动架构 SEDASEDA(Staged Event-Driven Architecture)的核心思想是把一个请求处理过程分成几个Stage,不同资源消耗的Stage使用不同数量的线程来处 ...
- 基于Java+Spring Boot开源项目JeeSite的Jenkins持续交互介绍
一.实战项目介绍- JeeSite 基于Spring Boot 2.0 数据存储MySQL 语言:Java 规模大小:适中,适合初学者 源码地址:https://gitee.com/thinkgem/ ...
- 各个复位标志解析,让我们对MCU的程序的健康更有把控
作者:良知犹存 转载授权以及围观:欢迎添加微信公众号:Conscience_Remains 总述 曾经开发的时候遇到这样情况,我们开发的设备需要长时间工作上报信息,但是我们在后台查看上报数据,发现设备 ...
- 2019牛客暑期多校训练营(第五场)H-subsequence 2 (拓扑排序+思维)
>传送门< 题意: 给你几组样例,给你两个字符a,b,一个长度len,一个长度为len的字符串str,str是字符串s的子串 str是s删掉除过a,b两字符剩下的子串,现在求s,多种情况输 ...