Github Repository 的正确打开姿势
毫无疑问,开源是伟大的
前言
作为一名前端开发者,日常编程完全离不开 “开源”。
从编辑器(VSCode,Atom),到用来做开发的MVVM(Vue.js,React.js,Angular.js)框架,到用来构建项目的包管理器(npm,yarn),再到项目中用到的各种UI库,第三方工具,组件。基本全是开源的,源码都能在Github搜到。
假如没有了开源,这个世界会是什么样?
这个世界会是什么样不好说,但完全可以想象的到程序员开发一款同样产品的难度会增加到多么可怕的地步。
我也经常在Github上开源一些东西,虽然不是一些什么难度很高,甚至还有些拙劣,可供优化的项目,但的确实实在在地帮到了一些人。他们通过阅读项目源码来学习新技术,在他们自己的项目中使用我的开源组件而省去了自己重新造轮子花费的大把时间,所以他们会给我的项目点Star,每一个Star都是对我项目的肯定。
正文
但什么是一个正常的开源项目呢?我认为必须符合以下几点
- 完整的文档(至少包含Preview 和 How To Use 两部分)
- 前者可以让开发者清晰明了的知道这是一个什么东西,是否符合他们的需求,而不是非得
Clone
下来亲自试试才知道这是什么鬼?- 如果
Clone
下来后发现并不符合心中的需求,那将让人感到非常挫败,而且也浪费了本不该浪费的时间。
- 如果
- 后者可以让开发者不必翻看你的源码而快速上手使用它。这也是开源的一大魅力,使用者不需要去阅读源码就能使用它。
- 开源项目的使用体验完全在于开发者。简单,优雅 应该是每一个开源项目开发者的信条。
- 前者可以让开发者清晰明了的知道这是一个什么东西,是否符合他们的需求,而不是非得
- 版本控制
- 关于版本控制的必要性,git文档说的很清楚了,粘贴过来一段就不复述了
- 有了它你就可以将某个文件回溯到之前的状态,甚至将整个项目都回退到过去某个时间点的状态。你可以比较文件的变化细节,查出最后是谁修改了哪个地方,从而找出导致怪异问题出现的原因,又是谁在何时报告了某个功能缺陷等等。使用版本控制系统通常还意味着,就算你乱来一气把整个项目中的文件改的改删的删,你也照样可以轻松恢复到原先的样子。但额外增加的工作量却微乎其微。
- 注释
- 必要的注释不仅让其他人在阅读你的源码时明白你写下这段代码时的思路,也能让你不会在一段时间后看不懂自己写的代码。
- 卧槽,当初这个地方我为什么要这么写?这是最让人尴尬的事情。
- 必要的注释不仅让其他人在阅读你的源码时明白你写下这段代码时的思路,也能让你不会在一段时间后看不懂自己写的代码。
- 正确的代码
- 本来不打算说这个,但在接连
Clone
了差不多有10个项目都报错时…… 我觉得还有很有必要说的。 - 既然咱都决定把代码开源出去了,为什么不能再费一点心,保证其他人
Clone
下来能正常运行呢?否则开源出去还有意义吗?
- 本来不打算说这个,但在接连
扯点别的
关于为什么要开源?
我的回答是:装逼
(我的一位室友有句口头禅,我觉得很有道理:“如果不是为了装逼,那将毫无意义!”)
更多角度的答案看这里
本文作者: 林水溶
Github https://github.com/shuiRong
本文链接: https://linshuirong.cn/blog/2018/04/02/Github-Repository-的正确打开姿势/
版权声明: 本作品采用 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议 进行许可。转载请注明出处!