Mythsman


努力工作,认真生活。


记在github中开发项目的正确姿势

前言

前几天随便写了一个hexo小插件,这几天刚好考完期末考试,趁着实习前没啥事,于是又拿来看看,想想有什么可以改进改进的。为了发散思路,我就把hexo.io的插件列表里的插件基本上从头到尾看了一遍。这个不看不知道,看完之后我发现其实里面的内容质量也是参差不齐的,好一点的呢,开发、测试、集成、样例、徽章都十分齐备,文档简明扼要,一看就是专业玩家;差一点的呢,基本都没有集成,没有测试,没有徽章,文档简陋或者啰嗦,有的issue满天也没人处理,有的build failure也不解决,更有的连repository都404了。。。看上去hexo的社区似乎在走下坡路了,毕竟博客这种东西,本来能坚持下来的人就不多,用户流失日益严重,而且hexo本身学习门槛也比较高,况且像这种项目还没有金主爸爸养,坚持维护也挺不容易的。
额。。。先不议论别人,还是先想办法提高提高自己项目的逼格吧。。。

修炼

有了目标就好办了,照着目标一点点前进就好了,下面就一个一个处理喽。

代码质量审查

说实话,虽然我这学期刚刚学了软件测试的课,但是其实大学的课程还是跟实际脱节很严重,学完课程之后对很多概念也没有切身的体会,直到自己真正上手写代码的时候才发现软件测试其实是在团队项目中非常实用的。
在这里,最常见的js代码质量审查工具就是Eslint
我们为什么要使用这个工具呢,这其实是为了更好的统一代码的编写规范。比如我们知道局部变量要用var来声明,字符串最好用单引号括,字典中最后一组后最好不要加逗号,不要写多余的分号等等很多约定俗成的最佳方案,但是如果我们不遵守这样的规定,显然也能照常解释执行,不过他的可维护性以及可读性肯定要比遵守这套最佳实践规范的代码低很多。
因此,为了整体提高代码质量,最好的方法就是用错误提示来强行要求我们采用最佳实践的规范,这就是Eslint这类工具的主要用途。
这让我想起了我在刚开始学C语言的时候,老师都建议我们,如果需要在if语句里面判断一个变量是否等于另一个数,最好采用if(0==x)而不是if(x==0)。说白了他的目的也是用错误提示来保证我们代码不容易出错,虽然我从来都不照他这么写。。。
当然,Eslint实际做的事情要复杂的多,他能够分析es5,es6之类的语法,在不运行代码的情况下分析出很多语法错误,可以说是非常方便了。
至于Eslint的具体用法我就不班门弄斧了,官网以及各种论坛都讲的很全,想用的时候随时学习就好了。

代码风格检查

说起代码风格,虽然看上去好像影响并不大,但是总会有些奇葩会采用非常神奇的缩进风格以及各种奇怪的对齐方案,总让人看的不舒服。不过还好,现在有很多IDE都能够自动进行代码格式化,所以从很大程度上将,代码风格应该没有太大问题。不过为了保证风格统一,减少编码人员带来的不确定性,我们一般都会做代码风格检查。
在这里,最初常见的js代码风格检查工具就是Jscs
这个Jscs大概做啥呢,举个例子,就是他会强行要求我们正确的缩进,代码块结束必须换行,且不能多次换行,函数声明()前要有空格,键值对前后要有空格,三目运算符的每一个符号前后必须要有空格等等。几乎牵涉到代码风格的问题他都能检查出来,而且这些风格也都可以进行配置,他也提供了很多大厂的优秀配置方案供我们选择。
基本上通过Jscs审查后的代码,至少从视觉上看都还是比较赏心悦目的。
不过仔细想想,其实Jscs的很多功能跟Eslint有重复,可以说从某种程度上讲,Jscs是Eslint的子集。最近打开Jscs的官网,发现果然Jscs即将要合并到Eslint里了。

代码测试

这个代码测试就不用多说了吧,重要性不言而喻,无论是理论上还是实践上,都非常重要。
在这里,最常见的js测试工具就是Mocha了,基本上所有的Nodejs工具书里都会讲,这大概算得上是基本功吧。
虽然很多情况下,我们自己写的测试用例都比较弱,但是通过了测试的代码至少是能跑起来的,不会出现太大的问题。毕竟软件的测试用例跟各种OJ的测试用例不一样,后者基本没有迭代,而且代码量很短,因此我们对软件测试用例的要求也不用太高吧~

代码覆盖率检查

这个代码覆盖率检查大概就是帮助我们写出更好的测试用例的,基本上是跟Mocha一起使用。
通常最常见的js代码覆盖率检查工具就是istanbul
只能说这个工具只能作为参考,覆盖率高也不一定就代表测试的质量高,覆盖率低也不一定就代表测试质量差,毕竟如果有异常捕获的情况下,让代码覆盖率上去也不是一件容易的事情。不过,作为一个完美主义者,代码覆盖率上不去总是让人有一种不舒服的感觉。。。

持续集成

说实话,持续集成这个概念我以前没怎么注意过,毕竟这个东西在简单项目里用的没啥意思(总共就commit一两次完事了有啥好集成的呢)。不过当项目需要持续维护的时候,尤其是多人维护的时候,就会发现,这类工具真特么有用。
比如,当别人pull了一个request,作为维护者得判断他的代码至少得跟当前分支兼容,并且运行起来不能报错。如果每次都下载下来手动进行测试,那得多麻烦~况且每次执行的东西都一样~我们完全可以写脚本来弄嘛~啊~写脚本也好麻烦啊~github你能不能自动帮我把每一个pull过来的request都自动跑一下测试啊啊啊。。。
我所理解的持续集成大概就是这个意思,Github也融合了持续集成的服务,这就是Travis CI
只要将Github账号绑定Travis CI,并且勾选需要持续集成的repo,在项目中配置好配置文件,那么只要项目有了新的commit,Travis CI就会在他的虚拟机里执行测试代码,返回成功或者失败,告诉我们这一次的commit是否靠谱。

插入徽章(badge)

所谓的badge实际上就是一张与项目实时同步的图片,能够简明扼要的反映项目的各种参数特征。基本用法就是在README.md里插入类似这样的代码[![图片的alt](图片的url)](发布badge的url)
badge这种东西用好了能嗖的提升项目的逼格,用得不好就是搬起石头砸自己的脚。毕竟这个逼也不是那么好装的。下面就稍微列举下我觉得有点意义的badge。

build status

Build Status


这个徽章可以从Travis CI这类的持续集成框架里搞到,每当有新的commit,他都会将值更新为最近一次的测试结果,成功则显示绿色的succcess,失败就显示红色的failure,非常醒目。

coverage

Coverage Status


这个徽章可以从coveralls.io这类测试框架里搞到,他会显示最近一次测试中返回的代码覆盖率,并以百分比的形式显示在徽章上,覆盖率越高,颜色越绿。。。

npm package

NPM version


这个徽章可以从badge.fury.io中获得,如果你的项目已经发布到了npmjs里,那么他就可以实时获得你的项目的最新版本号。

shields.io

npm
npm


shields.io这个网站里有非常多的徽章,可以通过这个网站找到很多你想要的徽章。我比较喜欢用npm版本徽章来显示目前项目支持的npm版本,用npm downloads之类的徽章来显示自己的包每天、每月、每年、总共的下载量等等。

Package quality

Package quality


这个徽章可以在packagequality.com里获得,用来简单的评价开发者对已发布在npmjs里的项目的支持程度。他的评价标准不是代码质量,而是项目的issue处理,版本迭代次数以及下载次数等情况。具体的算法也发布在他的github主页里,可供参考。

文档质量

这个就不细说了吧,其实我也不太会写,但是我总觉的一个好的文档至少得有下面几个部分:

  1. 项目简介
  2. 安装说明
  3. 参数说明
  4. 可以有使用截图
  5. 可以有demo网站
  6. 开源证书

唔。。。我总觉的我写的README应该还能说的过去把。。

Github设置

一般情况下,我们还是认真写下显示在Github上面的项目简介,以及topic选择,这样有助于别人找到自己的项目。
如果有经历的话,还是把release版本,tag版本,wiki搞搞全。。。(不过我总觉得一般小众一点的项目还是没必要搞这些幺蛾子了)