diff --git "a/\347\254\254\345\233\233\351\203\250\345\210\206\342\200\224\342\200\224\345\220\257\345\212\250\350\207\252\345\267\261\347\232\204\345\274\200\346\272\220\351\241\271\347\233\256/\344\270\272\345\274\200\346\272\220\351\241\271\347\233\256\345\273\272\347\253\213\350\211\257\345\245\275\347\232\204\345\237\272\347\241\200.md" "b/\347\254\254\345\233\233\351\203\250\345\210\206\342\200\224\342\200\224\345\220\257\345\212\250\350\207\252\345\267\261\347\232\204\345\274\200\346\272\220\351\241\271\347\233\256/\344\270\272\345\274\200\346\272\220\351\241\271\347\233\256\345\273\272\347\253\213\350\211\257\345\245\275\347\232\204\345\237\272\347\241\200.md" index 9d08415ca8dbaa7092baf18b645d356489cb0805..04df1d57d8315855c94bce206d94456145b1e292 100644 --- "a/\347\254\254\345\233\233\351\203\250\345\210\206\342\200\224\342\200\224\345\220\257\345\212\250\350\207\252\345\267\261\347\232\204\345\274\200\346\272\220\351\241\271\347\233\256/\344\270\272\345\274\200\346\272\220\351\241\271\347\233\256\345\273\272\347\253\213\350\211\257\345\245\275\347\232\204\345\237\272\347\241\200.md" +++ "b/\347\254\254\345\233\233\351\203\250\345\210\206\342\200\224\342\200\224\345\220\257\345\212\250\350\207\252\345\267\261\347\232\204\345\274\200\346\272\220\351\241\271\347\233\256/\344\270\272\345\274\200\346\272\220\351\241\271\347\233\256\345\273\272\347\253\213\350\211\257\345\245\275\347\232\204\345\237\272\347\241\200.md" @@ -1,4 +1,27 @@ ### 项目命名的学问 ### 如何打造一个优秀的 Readme ### 为项目撰写文档 -### 开源项目的代码质量要求 \ No newline at end of file +### 开源项目的代码质量要求 + + +一个认真打造的开源项目,肯定是希望有其他用户来使用,更希望有更多外部贡献者能参与进来。那么评价一个开源项目好不好,代码的质量就是非常重要的衡量指标了。 + +代码质量是程序员的基本功,说到这个话题,首先自然是需要去翻阅经典的专著了,《重构》、《设计模式》、《代码整洁之道》是程序员必备的手边书。 + +除了基本功之外,我们还需要保证代码的规范,比如命名、目录结构等。因为开源项目需要迎接来自世界各地的贡献者贡献的代码,为了保证代码的整体风格一致性,那么让贡献者共同遵守一个规范就非常有必要了。 + +代码规范一般都可以参考每个语言的官方规范,并借助静态检查、代码编辑器插件、lints 等工具,如常见的 EditorConfig、StyleCop、tslint、style lint 等等,在每个 Pull Request 时都先进行编码风格检查。 + +说到规范,还有就是进行 Git 分布式协作时的规范,如分支命名规范、commit message 规范、issue 模板、pull request 模板等等。把这些都拟定起来后,这个项目看起来就很正规、很美观。 + +而一个开源项目的质量,除了代码本身以外,更重要的是整个项目的状态。 + +首先最起码的是,这个项目必须编译通过。我们可以通过CI来把每次合并后的代码编译一遍,把编译状态通过 Badge 来展示。 + +第二点,就是运行状况。是否能正常运行也是最基本的检查点了,有条件的话最好是通过 CI/CD 来把 Demo 站点运行起来。有一个可让用户即时尝试的 Demo,对开源项目的成功是非常有帮助的。 + +第三点,就是单元测试覆盖率。覆盖率是对开源项目质量考察的标配的指标。覆盖率的检查可以通过集成 CodeCov 来做。它可以在每个 PR 中检查合并后对覆盖率的影响,合并后可以分析项目当前覆盖率,并可以用 Badge 来展示。同时,单元测试也对每个 PR 提出更高要求,必须全部通过了才给予合并。 + +第四点,就是外部贡献者数量。可能你会很奇怪,为什么我要把贡献者数量列进来?那是因为,他们对你这个项目的兴趣已经高到了会研究代码、并会贡献代码了,就能间接地说明这个项目的质量是有一定的分量的。他们愿意把它做得更好! + +第五点,生产案例。开源项目大多数是业余时间进行开发的,本身没有企业支持。那么,当它们被真正用于企业生产环境,并带来收益了,才说明这个项目是真正对用户有价值的。所以,开源项目可以收集一下用户的生产案例,一方面可以鼓励开源贡献者的付出、另一方面又可以展现这个项目的价值,还能对企业进行一定的宣传,这是三赢。