# 构建 GitHub 项目

## 如何用好 GitHub

如何用好 GitHub，并实践一些敏捷软件开发是一个很有意思的事情.我们可以在上面做很多事情,从测试到 CI,再到自动部署.

### 敏捷软件开发

显然我是在扯淡，这和敏捷软件开发没有什么关系。不过我也不知道瀑布流是怎样的。说说我所知道的一个项目的组成吧：

 - 看板式管理应用程序（如 trello，简单地说就是管理软件功能）
 - CI（持续集成）
 - 测试覆盖率
 - 代码质量（code smell）
 
对于一个不是远程的团队（如只有一个人的项目）来说，Trello、Jenkin、Jira不是必需的：

> 你存在，我深深的脑海里

当只有一个人的时候，你只需要明确知道自己想要什么就够了。我们还需要的是 CI、测试，以来提升代码的质量。

### 测试

通常我们都会找 Document，如果没有的话，你会找什么？看源代码，还是看测试？

```javascript
it("specifying response when you need it", function (done) {
	var doneFn = jasmine.createSpy("success");

	lettuce.get('/some/cool/url', function (result) {
		expect(result).toEqual("awesome response");
		done();
	});

	expect(jasmine.Ajax.requests.mostRecent().url).toBe('/some/cool/url');
	expect(doneFn).not.toHaveBeenCalled();

	jasmine.Ajax.requests.mostRecent().respondWith({
		"status": 200,
		"contentType": 'text/plain',
		"responseText": 'awesome response'
	});
});
```

代码来源：[https://github.com/phodal/lettuce](https://github.com/phodal/lettuce)

上面的测试用例，清清楚楚地写明了用法，虽然写得有点扯。

等等，测试是用来干什么的。那么，先说说我为什么会想去写测试吧：

 - 我不希望每次做完一个个新功能的时候，再手动地去测试一个个功能。（自动化测试）
 - 我不希望在重构的时候发现破坏了原来的功能，而我还一无所知。
 - 我不敢push代码，因为我没有把握。
 
虽然，我不是 TDD 的死忠，测试的目的是保证功能正常，TDD 没法让我们写出质量更高的代码。但是有时TDD是不错的，可以让我们写出逻辑更简单地代码。

也许你已经知道了``Selenium``、``Jasmine``、``Cucumber``等等的框架，看到过类似于下面的测试

```
 Ajax
   ✓ specifying response when you need it
   ✓ specifying html when you need it
   ✓ should be post to some where
 Class
   ✓ respects instanceof
   ✓ inherits methods (also super)
   ✓ extend methods
 Effect
   ✓ should be able fadein elements
   ✓ should be able fadeout elements
```

代码来源：[https://github.com/phodal/lettuce](https://github.com/phodal/lettuce)
	   
看上去似乎每个测试都很小，不过补完每一个测试之后我们就得到了测试覆盖率

File | Statements | Branches | Functions | Lines
-----|------------|----------|-----------|------
lettuce.js	| 98.58% (209 / 212)| 82.98%(78 / 94) | 100.00% (54 / 54) | 98.58% (209 / 212)

本地测试都通过了，于是我们添加了``Travis-CI``来跑我们的测试

### CI

虽然 node.js 不算是一门语言，但是因为我们用的 node，下面的是一个简单的 ``.travis.yml`` 示例：

```yml
language: node_js
node_js:
	- "0.10"

notifications:
	email: false

before_install: npm install -g grunt-cli
install: npm install
after_success: CODECLIMATE_REPO_TOKEN=321480822fc37deb0de70a11931b4cb6a2a3cc411680e8f4569936ac8ffbb0ab codeclimate < coverage/lcov.info
```

代码来源：[https://github.com/phodal/lettuce](https://github.com/phodal/lettuce)

我们把这些集成到 ``README.md`` 之后，就有了之前那张图。

CI对于一个开发者在不同城市开发同一项目上来说是很重要的，这意味着当你添加的部分功能有测试覆盖的时候，项目代码会更加强壮。

### 代码质量

像 ``jslint`` 这类的工具，只能保证代码在语法上是正确的，但是不能保证你写了一堆 bad smell 的代码。

 - 重复代码
 - 过长的函数
 - 等等
 
``Code Climate`` 是一个与 GitHub 集成的工具，我们不仅仅可以看到测试覆盖率，还有代码质量。

先看看上面的 ajax 类：

```javascript
Lettuce.get = function (url, callback) {
	Lettuce.send(url, 'GET', callback);
};

Lettuce.send = function (url, method, callback, data) {
	data = data || null;
	var request = new XMLHttpRequest();
	if (callback instanceof Function) {
		request.onreadystatechange = function () {
			if (request.readyState === 4 && (request.status === 200 || request.status === 0)) {
				callback(request.responseText);
			}
		};
	}
	request.open(method, url, true);
	if (data instanceof Object) {
		data = JSON.stringify(data);
		request.setRequestHeader('Content-Type', 'application/json');
	}
	request.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
	request.send(data);
};
```

代码来源：[https://github.com/phodal/lettuce](https://github.com/phodal/lettuce)

在 [Code Climate](https://codeclimate.com/github/phodal/lettuce/src/ajax.js) 在出现了一堆问题

 - Missing "use strict" statement. (Line 2)
 - Missing "use strict" statement. (Line 14)
 - 'Lettuce' is not defined. (Line 5)

而这些都是小问题啦，有时可能会有

 - Similar code found in two :expression_statement nodes (mass = 86)

这就意味着我们可以对上面的代码进行重构，他们是重复的代码。

## 模块分离与测试

在之前说到

> 奋斗了近半个月后，将 fork 的代码读懂、重构、升级版本、调整，添加新功能、添加测试、添加 CI、添加分享之后，终于 almost finish。

今天就来说说是怎样做的。

以之前造的 [Lettuce](https://github.com/phodal/lettuce) 为例，里面有：

 - 代码质量（Code Climate）
 - CI状态（Travis CI）
 - 测试覆盖率（96%）
 - 自动化测试（npm test）
 - 文档

按照 [Web Developer 路线图](https://github.com/phodal/awesome-developer)来说，我们还需要有：

 - 版本管理
 - 自动部署
 
等等。 

### 代码模块化

在 SkillTree 的源码里，大致分为三部分：

 - namespace 函数：顾名思义
 - Calculator 也就是 TalentTree，主要负责解析、生成 url，头像，依赖等等
 - Skill 主要是 tips 部分。
 
而这一些都在一个 JS 里，对于一个库来说，是一件好事，但是对于一个项目来说，并非如此。 

依赖的库有

 - jQuery
 - Knockout
 
好在 Knockout 可以用 Require.js 进行管理，于是，使用了 ``Require.js`` 进行管理：

```html
<script type="text/javascript" data-main="app/scripts/main.js" src="app/lib/require.js"></script>
```

``main.js`` 配置如下：

```javascript
require.config({
  baseUrl: 'app',
  paths:{
    jquery: 'lib/jquery',
    json: 'lib/json',
    text: 'lib/text'
  }
});

require(['scripts/ko-bindings']);

require(['lib/knockout', 'scripts/TalentTree', 'json!data/web.json'], function(ko, TalentTree, TalentData) {
  'use strict';
  var vm = new TalentTree(TalentData);
  ko.applyBindings(vm);
});
```
	
text、JSON 插件主要是用于处理 web.json，即用 JSON 来处理技能，于是不同的类到了不同的 JS 文件。

	.
	|____Book.js
	|____Doc.js
	|____ko-bindings.js
	|____Link.js
	|____main.js
	|____Skill.js
	|____TalentTree.js
	|____Utils.js
	
加上了后来的推荐阅读书籍等等。而 Book 和 Link 都是继承自 Doc。

```javascript
define(['scripts/Doc'], function(Doc) {
  'use strict';
  function Book(_e) {
    Doc.apply(this, arguments);
  }
  Book.prototype = new Doc();

  return Book;
});	
```

而这里便是后面对其进行重构的内容。Doc 类则是 Skillock 中类的一个缩影

```javascript
define([], function() {
  'use strict';
  var Doc = function (_e) {
    var e = _e || {};
    var self = this;

    self.label = e.label || (e.url || 'Learn more');
    self.url = e.url || 'javascript:void(0)';
  };

  return Doc;
});
```

或者说这是一个 AMD 的 Class 应该有的样子。考虑到 this 的隐性绑定，作者用了self=this 来避免这个问题。最后 Return 了这个对象，我们在调用的就需要 new 一个。大部分在代码中返回的都是对象，除了在 Utils 类里面返回的是函数：

```javascript
return {
    getSkillsByHash: getSkillsByHash,
    getSkillById: getSkillById,				
    prettyJoin: prettyJoin
};
```
	
当然函数也是一个对象。	

### 自动化测试

一直习惯用 Travis CI，于是也继续用 Travis Ci，``.travis.yml`` 配置如下所示：

```yml
language: node_js
node_js:
  - "0.10"

notifications:
  email: false

branches:
  only:
    - gh-pages
```

使用 gh-pages 的原因是，我们一 push 代码的时候，就可以自动测试、部署等等，好处一堆堆的。

接着我们需要在 ``package.json`` 里面添加脚本

```javascript
"scripts": {
    "test": "mocha"
  }
```
	  
这样当我们 push 代码的时候便会自动跑所有的测试。因为 mocha 的主要配置是用 ``mocha.opts``，所以我们还需要配置一下 ``mocha.opts``

	--reporter spec
	--ui bdd
	--growl
	--colors
	test/spec	  

最后的 ``test/spec`` 是指定测试的目录。

### JSLint

> JSLint定义了一组编码约定，这比ECMA定义的语言更为严格。这些编码约定汲取了多年来的丰富编码经验，并以一条年代久远的编程原则 作为宗旨：能做并不意味着应该做。JSLint会对它认为有的编码实践加标志，另外还会指出哪些是明显的错误，从而促使你养成好的 JavaScript编码习惯。

当我们的 JS 写得不合理的时候，这时测试就无法通过：

	line 5   col 25   A constructor name should start with an uppercase letter.
	line 21  col 62   Strings must use singlequote.
	
这是一种驱动写出更规范 JS 的方法。


### Mocha

> Mocha 是一个优秀的JS测试框架，支持TDD/BDD，结合 should.js/expect/chai/better-assert，能轻松构建各种风格的测试用例。

最后的效果如下所示：

    Book,Link
      Book Test
        ✓ should return book label & url
      Link Test
        ✓ should return link label & url

### 测试示例

简单地看一下 Book 的测试：

```javascript
/* global describe, it */

var requirejs = require("requirejs");
var assert = require("assert");
var should = require("should");
requirejs.config({
  baseUrl: 'app/',
  nodeRequire: require
});

describe('Book,Link', function () {
  var Book, Link;
  before(function (done) {
    requirejs(['scripts/Book'、], function (Book_Class) {
      Book = Book_Class;
      done();
    });
  });

  describe('Book Test', function () {
    it('should return book label & url', function () {
      var book_name = 'Head First HTML与CSS';
      var url = 'http://www.phodal.com';
      var books = {
        label: book_name,
        url: url
      };

      var _book = new Book(books);
      _book.label.should.equal(book_name);
      _book.url.should.equal(url);
    });
  });
});
```

因为我们用 ``require.js`` 来管理浏览器端，在后台写测试来测试的时候，我们也需要用他来管理我们的依赖，这也就是为什么这个测试这么长的原因，多数情况下一个测试类似于这样子的。（用 Jasmine 似乎会是一个更好的主意，但是用习惯 Jasmine 了）

```javascript
describe('Book Test', function () {
it('should return book label & url', function () {
  var book_name = 'Head First HTML与CSS';
  var url = 'http://www.phodal.com';
  var books = {
    label: book_name,
    url: url
  };

  var _book = new Book(books);
  _book.label.should.equal(book_name);
  _book.url.should.equal(url);
});
});
```

最后的断言，也算是测试的核心，保证测试是有用的。	  

## 代码质量与重构

 - 当你写了一大堆代码,你没有意识到里面有一大堆重复。
 - 当你写了一大堆测试,却不知道覆盖率有多少。

这就是个问题了，于是偶然间看到了一个叫 code climate 的网站。

### Code Climate

> Code Climate consolidates the results from a suite of static analysis tools into a single, real-time report, giving your team the information it needs to identify hotspots, evaluate new approaches, and improve code quality.

Code Climate 整合一组静态分析工具的结果到一个单一的，实时的报告，让您的团队需要识别热点，探讨新的方法，提高代码质量的信息。

简单地来说：

- 对我们的代码评分
- 找出代码中的坏味道

于是，我们先来了个例子

| Rating | Name                             | Complexity | Duplication | Churn | C/M  | Coverage | Smells |
| ------ | -------------------------------- | ---------- | ----------- | ----- | ---- | -------- | ------ |
| A      | lib/coap/coap_request_handler.js | 24         | 0           | 6     | 2.6  | 46.4%    | 0      |
| A      | lib/coap/coap_result_helper.js   | 14         | 0           | 2     | 3.4  | 80.0%    | 0      |
| A      | lib/coap/coap_server.js          | 16         | 0           | 5     | 5.2  | 44.0%    | 0      |
| A      | lib/database/db_factory.js       | 8          | 0           | 3     | 3.8  | 92.3%    | 0      |
| A      | lib/database/iot_db.js           | 7          | 0           | 6     | 1.0  | 58.8%    | 0      |
| A      | lib/database/mongodb_helper.js   | 63         | 0           | 11    | 4.5  | 35.0%    | 0      |
| C      | lib/database/sqlite_helper.js    | 32         | 86          | 10    | 4.5  | 35.0%    | 2      |
| B      | lib/rest/rest_helper.js          | 19         | 62          | 3     | 4.7  | 37.5%    | 2      |
| A      | lib/rest/rest_server.js          | 17         | 0           | 2     | 8.6  | 88.9%    | 0      |

分享得到的最后的结果是：

![Coverage][1]

### 代码的坏味道

于是我们就打开 ``lib/database/sqlite_helper.js``，因为其中有两个坏味道

Similar code found in two :expression_statement nodes (mass = 86)

在代码的 ``lib/database/sqlite_helper.js:58…61 < >``

```javascript
    SQLiteHelper.prototype.deleteData = function (url, callback) {
        'use strict';
        var sql_command = "DELETE FROM  " + config.table_name + "  where " + URLHandler.getKeyFromURL(url) + "=" + URLHandler.getValueFromURL(url);
        SQLiteHelper.prototype.basic(sql_command, callback);
```
        
lib/database/sqlite_helper.js:64…67 < >

与

```javascript
SQLiteHelper.prototype.getData = function (url, callback) {
    'use strict';
    var sql_command = "SELECT * FROM  " + config.table_name + "  where " + URLHandler.getKeyFromURL(url) + "=" + URLHandler.getValueFromURL(url);
    SQLiteHelper.prototype.basic(sql_command, callback);
```

只是这是之前修改过的重复。。

原来的代码是这样的

```javascript
SQLiteHelper.prototype.postData = function (block, callback) {
    'use strict';
    var db = new sqlite3.Database(config.db_name);
    var str = this.parseData(config.keys);
    var string = this.parseData(block);

    var sql_command = "insert or replace into " + config.table_name + " (" + str + ") VALUES (" + string + ");";
    db.all(sql_command, function (err) {
        SQLiteHelper.prototype.errorHandler(err);
        db.close();
        callback();
    });
};

SQLiteHelper.prototype.deleteData = function (url, callback) {
    'use strict';
    var db = new sqlite3.Database(config.db_name);
    var sql_command = "DELETE FROM  " + config.table_name + "  where " + URLHandler.getKeyFromURL(url) + "=" + URLHandler.getValueFromURL(url);
    db.all(sql_command, function (err) {
        SQLiteHelper.prototype.errorHandler(err);
        db.close();
        callback();
    });
};

SQLiteHelper.prototype.getData = function (url, callback) {
    'use strict';
    var db = new sqlite3.Database(config.db_name);
    var sql_command = "SELECT * FROM  " + config.table_name + "  where " + URLHandler.getKeyFromURL(url) + "=" + URLHandler.getValueFromURL(url);
    db.all(sql_command, function (err, rows) {
        SQLiteHelper.prototype.errorHandler(err);
        db.close();
        callback(JSON.stringify(rows));
    });
};
```
说的也是大量的重复，重构完的代码

```javascript
SQLiteHelper.prototype.basic = function(sql, db_callback){
    'use strict';
    var db = new sqlite3.Database(config.db_name);
    db.all(sql, function (err, rows) {
        SQLiteHelper.prototype.errorHandler(err);
        db.close();
        db_callback(JSON.stringify(rows));
    });

};

SQLiteHelper.prototype.postData = function (block, callback) {
    'use strict';
    var str = this.parseData(config.keys);
    var string = this.parseData(block);

    var sql_command = "insert or replace into " + config.table_name + " (" + str + ") VALUES (" + string + ");";
    SQLiteHelper.prototype.basic(sql_command, callback);
};

SQLiteHelper.prototype.deleteData = function (url, callback) {
    'use strict';
    var sql_command = "DELETE FROM  " + config.table_name + "  where " + URLHandler.getKeyFromURL(url) + "=" + URLHandler.getValueFromURL(url);
    SQLiteHelper.prototype.basic(sql_command, callback);
};

SQLiteHelper.prototype.getData = function (url, callback) {
    'use strict';
    var sql_command = "SELECT * FROM  " + config.table_name + "  where " + URLHandler.getKeyFromURL(url) + "=" + URLHandler.getValueFromURL(url);
    SQLiteHelper.prototype.basic(sql_command, callback);
};
```

重构完后的代码比原来还长，这似乎是个问题~~