datavjs

datavjs Version: 0.1.1 By @DataV

DataV.js is a JavaScript library for data visualization

DataV项目编码规范

一套良好的编码规范如果在团队开发中被遵守，可以降低团队成员之间交流的成本，同时也降低犯错的几率。可以说编码规范只需花费20%的精力来遵循，却可以降低80%的犯低级错误几率。 这一版的编码规范，主要查考了Douglas Crockford的JSLint的检查条件和过去的一些编码经验，整理而出。

命名空间

项目的总命名空间为：DataV。
除了Rapheal和D3自身的代码外，我们提交的任何方法都应该挂载在DataV命名空间中。 例外：某些方法和功能可以独立抽取出来，适用于别的项目。但是也应该由一个命名空间来管理它们。

语法

缩进规范

由于该项目是普通的前端JavaScript项目，所以缩进采用4个空格的方式。禁止使用tab符号。 推荐更改编辑器中的设置，使得按tab键可以自动插入4个空格。 每一层级之间，要保证缩进是正确的。

空格

  • =前后应该存在一个空格
  • (前面应该存在一个空格
  • )后面应该存在一个空格
  • {前面应该存在一个空格

分号

每一个申明或者定义，都应该以分号结尾。 

var username = "Jackson";

var foo = function () {};

每一行调用都应该明确以分号结尾。 

foo();

大括号

请明确使用{}来约束代码段。 推荐： 

if (condition) {
    foo = "bar";
}

不推荐： 

if (condition) boo = "bar";

命名规范

变量

采用驼峰首字母小写，后续单词均需大写首字母，不得在中间包含下划线。 每一个变量都应该通过var申明，以防止变量污染。 正确: 

var pipeChart;

错误： 

var pipechart;
var pipe_chart;

方法

方法名同变量名，采用驼峰式命名。 定义方法均通过var foo = function () {};而不是function foo () {}。 

var foo = function () {
    // TODO
};

方法名应该可以表示方法的行为和暗示方法的返回值。善用set、get、is、has等方法前缀。

类

由于JavaScript中类和方法的关键字都是function，为了区别两者的混淆，类名的定义通常是大写首字母，以表示它是一个作为类来调用的。 

var Person = function () {
    // TODO
};

类的方法请尽量赋值在prototype属性上，使得通过原型链查找的方式降低内存占用。 类的数据请尽量在构造函数中赋值，以加快执行时的查找速度。 

var Person = function (age) {
    this.age = age; // 在构造函数中赋值数据
};

// 在原型链中设置方法
Person.prototype.getAge = function () {
    return this.age;
};

对于私有方法，在前面添加下划线表示不推荐被外部调用。 

Persion.prototype._sleep = function () {};

模块

为了统一规划，我们的类均需通过模块的定义方式，与命名空间结合，以保证环境的干净。 

(function () {
    var private = "I am private";
    var Person = function () {
        this.username = private;
    };

    DataV.Person = Person;
}());

注释

注释对于团队而言是十分重要的，每一个方法都应该包含说明。
必选的注释是方法的说明，方法的参数，和一个例子。
任何诡异的地方，都应该附有简单的注释来描述它，以提醒后来人注意，以区别对待。 

/**
 * Create chart panel by passin width and height
 * @param {string} type Type name
 * @param {number} width Chart panel's width value
 * @param {number} height Chart panel's height value
 * @example
 * createChart("pipe", 500, 500);
 */
var createChart = function (type, width, height) {
    // Trick comments
    trickCall();
};

通过jsdoc的注释，将利于我们后期导出API文档。

文件名（以及目录）

文件名的方式也是通过驼峰式，但是以下划线分割单词，一律小写单词。如： 

d3.js
child_process.js

JSLint扫描代码

JSLint的调用方式如下： 

node precommit.js file

配置方式存放在config.json中。

目录结构说明

目前datav组件库的目录结构如下： 

JacksonTianmatoMacBook-Pro:datav.js jacksontian$ tree -d
.
├── bin
├── deps
├── doc
├── example
├── lib
└── test

其中详细说明一下：

  • bin目录用于存放一些可运行的脚本或者工具，例如jslint。
  • deps目录用于存放项目的依赖文件，其中有raphael和d3的相关文件。
  • doc目录用于用于存放项目的文档，如API生成文档或一些说明文档。
  • example目录存放案例代码。
  • lib目录为组件库具体代码，根据每个图的类型不同，存为对应文件。
  • test目录存放单元测试代码或自动化测试代码。

单元测试

DataV项目采用QUnit作为测试框架，详细文档请见。
简单测试例子： 

// 分模块
module("DataV");
// 测试用例
test("Themes.get", function () {
    // 单个断言
    equal(DataV.Themes.get("inexsit"), undefined, "Should get undefined when key is inexsit");
    equal(DataV.Themes.get("COLOR_MODE"), "gradient", "Should get gradient when key is COLOR_MODE");
    equal(typeof DataV.Themes.get("COLOR_ARGS"), "object", "COLOR_ARGS should be an object");
    equal(DataV.Themes.get("COLOR_ARGS").length, 2, "COLOR_ARGS should have two items");
});

数据格式

数据格式统一采用二维表的方式，结构比较类似数据库中的表。列名通过文档详细来描述，写在代码的jsdoc的注释中。 标准数据格式例子如下： 

/**
 * 设置数据源
 * Example 举个例字，假设下面的数组表示2个人在一年4个季度的消费。第一个人在4个季度里消费了1、2、3、9元。第二个人消费了3、4、6、3元。
 * [
 *  [1,2,3,9],
 *  [3,4,6,3]
 * ]
 * @param {Array} source 数据源数组.
 */
Stream.prototype.setSource = function (source) {
    // TODO
};

所有的组件库的调用都是相同的接口setSource： 

var stream = new DataV.Stream("chart");
stream.setSource(source);
stream.render();

事件注入

每一个组件都可能向外提供一些事件钩子，包括DOM事件，或者业务逻辑事件。绑定的方式十分简单： 

stream.on("click", function (event) {
  console.log(event);
});

stream.on("dblclick", function (event) {
  alert("double click");
});

stream.on("contextmenu", function (event) {
  alert("mouse right");
});

组件的内部实现是通过继承EventProxy提供自定义方式，在创建画布后，就绑定一些必要的事件到画布节点上，然后将事件触发出去。如果用户如上文，侦听了这些业务事件，将会调用执行。 

Stream.prototype.createCanvas = function () {
  var conf = this.defaults;
  this.canvas = Raphael(this.node, conf.width, conf.height);
  this.DOMNode = $(this.canvas.canvas);
  var that = this;
  this.DOMNode.click(function (event) {
    that.trigger("click", event);
  });
  this.DOMNode.dblclick(function (event) {
    that.trigger("dblclick", event);
  });
  this.DOMNode.bind("contextmenu", function (event) {
    that.trigger("contextmenu", event);
  });
  this.DOMNode.delegate("path", "click", function (event) {
    that.trigger("path_click", event);
  });
};

常见错误

判断一个对象是否是数组

下面是宁朗写的： 

if (color.constructor !== Array) {
  throw new Error("The color should be Array");
}

下面是Underscore的方法： 

_.isArray = nativeIsArray || function(obj) {
  return toString.call(obj) == '[object Array]';
};

数组去重

// make an array's every element unique by delete other same element 
Array.prototype.uniq = function () {
  var temp = {},
    len = this.length;

  for (var i = 0; i < len; i++) {
    if (typeof temp[this[i]] == "undefined") {
      temp[this[i]] = 1;
    }
  }
  this.length = 0;
  len = 0;
  for (var i in temp) {
    this[len++] = i;
  }
  return this;
};

这里可以调用underscore的uniq方法即可。节省N行代码量

元素是否存在数组中

//check if a string is in an array
var _strInArray = function (str, array) {
  var i = 0,
    l = 0;
  for (i = 0, l = array.length; i < l; i++) {
    if (array[i] === str) {
      return true;
    }
  }
  return false;
};

换用_.indexOf(array, value)可以节省代码量，且返回值比boolean值更有价值

meta

<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />

希望大家潮一点，别在写上面那行代码了。下面的表达方式更简洁，且无任何副作用。 

<meta charset="utf-8" />

script标签的type属性

如果是默认的text/javascript的话，就可以直接省略掉。变成下面这样子：

=======

DataV项目编码规范

一套良好的编码规范如果在团队开发中被遵守，可以降低团队成员之间交流的成本，同时也降低犯错的几率。可以说编码规范只需花费20%的精力来遵循，却可以降低80%的犯低级错误几率。 这一版的编码规范，主要查考了Douglas Crockford的JSLint的检查条件和过去的一些编码经验，整理而出。

命名空间

项目的总命名空间为：DataV。
除了Rapheal和D3自身的代码外，我们提交的任何方法都应该挂载在DataV命名空间中。 例外：某些方法和功能可以独立抽取出来，适用于别的项目。但是也应该由一个命名空间来管理它们。

语法

缩进规范

由于该项目是普通的前端JavaScript项目，所以缩进采用2个空格的方式。禁止使用tab符号。 推荐更改编辑器中的设置，使得按tab键可以自动插入2个空格。 每一层级之间，要保证缩进是正确的。

空格

  • =前后应该存在一个空格
  • (前面应该存在一个空格
  • )后面应该存在一个空格
  • {前面应该存在一个空格

分号

每一个申明或者定义，都应该以分号结尾。 

var username = "Jackson";

var foo = function () {};

每一行调用都应该明确以分号结尾。 

foo();

大括号

请明确使用{}来约束代码段。 推荐： 

if (condition) {
    foo = "bar";
}

不推荐： 

if (condition) boo = "bar";

命名规范

变量

采用驼峰首字母小写，后续单词均需大写首字母，不得在中间包含下划线。 每一个变量都应该通过var申明，以防止变量污染。 正确: 

var pipeChart;

错误： 

var pipechart;
var pipe_chart;

方法

方法名同变量名，采用驼峰式命名。 定义方法均通过var foo = function () {};而不是function foo () {}。 

var foo = function () {
    // TODO
};

方法名应该可以表示方法的行为和暗示方法的返回值。善用set、get、is、has等方法前缀。

类

由于JavaScript中类和方法的关键字都是function，为了区别两者的混淆，类名的定义通常是大写首字母，以表示它是一个作为类来调用的。 

var Person = function () {
    // TODO
};

类的方法请尽量赋值在prototype属性上，使得通过原型链查找的方式降低内存占用。 类的数据请尽量在构造函数中赋值，以加快执行时的查找速度。 

var Person = function (age) {
    this.age = age; // 在构造函数中赋值数据
};

// 在原型链中设置方法
Person.prototype.getAge = function () {
    return this.age;
};

对于私有方法，在前面添加下划线表示不推荐被外部调用。 

Persion.prototype._sleep = function () {};

模块

为了统一规划，我们的类均需通过模块的定义方式，与命名空间结合，以保证环境的干净。 

(function () {
    var private = "I am private";
    var Person = function () {
        this.username = private;
    };

    DataV.Person = Person;
}());

注释

注释对于团队而言是十分重要的，每一个方法都应该包含说明。
必选的注释是方法的说明，方法的参数，和一个例子。
任何诡异的地方，都应该附有简单的注释来描述它，以提醒后来人注意，以区别对待。 

/**
 * Create chart panel by passin width and height
 * @param {string} type Type name
 * @param {number} width Chart panel's width value
 * @param {number} height Chart panel's height value
 * @example
 * createChart("pipe", 500, 500);
 */
var createChart = function (type, width, height) {
    // Trick comments
    trickCall();
};

通过jsdoc的注释，将利于我们后期导出API文档。

文件名

文件名的方式也是通过驼峰式，但是以下划线分割单词，一律小写单词。如： 

d3.js
child_process.js

文件内容

换行符

请用Unix的CRLF换行符

文件编码

请用UTF-8 without BOM作为文件内容的编码

JSLint扫描代码

JSLint的调用方式如下： 

node precommit.js file

配置方式存放在config.json中。

目录结构说明

目前datav组件库的目录结构如下： 

JacksonTianmatoMacBook-Pro:datav.js jacksontian$ tree -d
.
├── bin
├── deps
├── doc
├── example
├── lib
└── test

其中详细说明一下：

  • bin目录用于存放一些可运行的脚本或者工具，例如jslint。
  • deps目录用于存放项目的依赖文件，其中有raphael和d3的相关文件。
  • doc目录用于用于存放项目的文档，如API生成文档或一些说明文档。
  • example目录存放案例代码。
  • lib目录为组件库具体代码，根据每个图的类型不同，存为对应文件。
  • test目录存放单元测试代码或自动化测试代码。

单元测试

DataV项目采用QUnit作为测试框架，详细文档请见。
简单测试例子： 

// 分模块
module("DataV");
// 测试用例
test("Themes.get", function () {
    // 单个断言
    equal(DataV.Themes.get("inexsit"), undefined, "Should get undefined when key is inexsit");
    equal(DataV.Themes.get("COLOR_MODE"), "gradient", "Should get gradient when key is COLOR_MODE");
    equal(typeof DataV.Themes.get("COLOR_ARGS"), "object", "COLOR_ARGS should be an object");
    equal(DataV.Themes.get("COLOR_ARGS").length, 2, "COLOR_ARGS should have two items");
});

数据格式

数据格式统一采用二维表的方式，结构比较类似数据库中的表。列名通过文档详细来描述，写在代码的jsdoc的注释中。 标准数据格式例子如下： 

/**
 * 设置数据源
 * Example 举个例字，假设下面的数组表示2个人在一年4个季度的消费。第一个人在4个季度里消费了1、2、3、9元。第二个人消费了3、4、6、3元。
 * [
 *  [1,2,3,9],
 *  [3,4,6,3]
 * ]
 * @param {Array} source 数据源数组.
 */
Stream.prototype.setSource = function (source) {
    // TODO
};

所有的组件库的调用都是相同的接口setSource： 

var stream = new DataV.Stream("chart");
stream.setSource(source);
stream.render();

事件注入

每一个组件都可能向外提供一些事件钩子，包括DOM事件，或者业务逻辑事件。绑定的方式十分简单： 

stream.on("click", function (event) {
  console.log(event);
});

stream.on("dblclick", function (event) {
  alert("double click");
});

stream.on("contextmenu", function (event) {
  alert("mouse right");
});

组件的内部实现是通过继承EventProxy提供自定义方式，在创建画布后，就绑定一些必要的事件到画布节点上，然后将事件触发出去。如果用户如上文，侦听了这些业务事件，将会调用执行。 

Stream.prototype.createCanvas = function () {
  var conf = this.defaults;
  this.canvas = Raphael(this.node, conf.width, conf.height);
  this.DOMNode = $(this.canvas.canvas);
  var that = this;
  this.DOMNode.click(function (event) {
    that.trigger("click", event);
  });
  this.DOMNode.dblclick(function (event) {
    that.trigger("dblclick", event);
  });
  this.DOMNode.bind("contextmenu", function (event) {
    that.trigger("contextmenu", event);
  });
  this.DOMNode.delegate("path", "click", function (event) {
    that.trigger("path_click", event);
  });
};

常见错误

判断一个对象是否是数组

下面是宁朗写的： 

if (color.constructor !== Array) {
  throw new Error("The color should be Array");
}

下面是Underscore的方法： 

_.isArray = nativeIsArray || function(obj) {
  return toString.call(obj) == '[object Array]';
};

数组去重

// make an array's every element unique by delete other same element 
Array.prototype.uniq = function () {
  var temp = {},
    len = this.length;

  for (var i = 0; i < len; i++) {
    if (typeof temp[this[i]] == "undefined") {
      temp[this[i]] = 1;
    }
  }
  this.length = 0;
  len = 0;
  for (var i in temp) {
    this[len++] = i;
  }
  return this;
};

这里可以调用underscore的uniq方法即可。节省N行代码量

元素是否存在数组中

//check if a string is in an array
var _strInArray = function (str, array) {
  var i = 0,
    l = 0;
  for (i = 0, l = array.length; i < l; i++) {
    if (array[i] === str) {
      return true;
    }
  }
  return false;
};

换用_.indexOf(array, value)可以节省代码量，且返回值比boolean值更有价值

meta

<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />

希望大家潮一点，别在写上面那行代码了。下面的表达方式更简洁，且无任何副作用。 

<meta charset="utf-8" />

script标签的type属性

如果是默认的text/javascript的话，就可以直接省略掉。变成下面这样子：