构建 GitHub 项目

构建 GitHub 项目

如何用好 GitHub

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

敏捷软件开发

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

看板式管理应用程序(如trello，简单地说就是管理软件功能)
CI(持续集成)
测试覆盖率
代码质量(code smell)

对于一个不是远程的团队(如只有一个人的项目) 来说，Trello、Jenkin、Jira不是必需的:

你存在，我深深的脑海里

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

测试

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

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

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

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

我不希望每次做完一个个新功能的时候，再手动地去测试一个个功能。(自动化测试)
我不希望在重构的时候发现破坏了原来的功能，而我还一无所知。
我不敢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

看上去似乎每个测试都很小，不过补完每一个测试之后我们就得到了测试覆盖率

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示例:

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

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

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

代码质量

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

重复代码
过长的函数
等等

Code Climate是一个与github集成的工具，我们不仅仅可以看到测试覆盖率，还有代码质量。

先看看上面的ajax类:

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

在Code Climate在出现了一堆问题

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为例，里面有:

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

按照Web Developer路线图来说，我们还需要有:

版本管理
自动部署

等等。

代码模块化

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

namespace函数: 顾名思义
Calculator也就是TalentTree，主要负责解析、生成url，头像，依赖等等
Skill 主要是tips部分。

而这一些都在一个js里，对于一个库来说，是一件好事，但是对于一个项目来说，并非如此。

依赖的库有

jQuery
Knockout

好在Knockout可以用Require.js进行管理，于是，使用了Require.js进行管理:

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

main.js配置如下:

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。

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

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

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类里面返回的是函数:

return {
    getSkillsByHash: getSkillsByHash,
    getSkillById: getSkillById,                
    prettyJoin: prettyJoin
};

当然函数也是一个对象。

自动化测试

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

language: node_js
node_js:
  - "0.10"
notifications:
  email: false
branches:
  only:
    - gh-pages

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

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

"scripts": {
    "test": "mocha"
  }

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

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

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

Jshint

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的测试:

/* 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了)

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
A	lib/url_handler.js	9	0	5	2.2	94.1%	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 < >

    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 < >

与

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);

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

原来的代码是这样的

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));
    });
};

说的也是大量的重复，重构完的代码

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);
};

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

03. 构建 GitHub 项目

构建 GitHub 项目

如何用好 GitHub

敏捷软件开发

测试

CI

代码质量

模块分离与测试

代码模块化

自动化测试

Jshint

Mocha

测试示例

代码质量与重构

Code Climate

代码的坏味道