前言

Star多的项目就一定规范与优雅？文档是应放在wiki中还是code repo中？readme越简洁越好，还是越详尽越好？readme写中文还是英文？此文一网打尽，解读存在你脑海里的开源误区。记不住可是要分分钟被小白教做人哦！

腾讯开源沙龙邀请到了多位腾讯开源项目作者，其中近日开源的微信生物认证平台与标准TENCENT SOTER作者Henryye，以一个开源“小白”的身份，分享自己在开源路上踩过的“坑”。

嘉宾介绍

Henryye
Henryye，叶轩，来自腾讯微信事业群，主要负责腾讯开源项目TENCENT SOTER生物认证平台的开发、维护与运营。

项目介绍

TENCENT SOTER
TENCENT SOTER是腾讯于2015年开始制定的生物认证平台与标准，目前已经在微信指纹支付、微信公众号/小程序指纹授权接口等场景使用，并得到了验证。接入TENCENT SOTER之后，开发者可以在不获取用户指纹图案的前提下，在Android设备上实现可信的指纹认证，获得与微信指纹支付一致的安全快捷认证体验。
开源地址：
https://github.com/Tencent/soter

以下是演讲实录：

TENCENT SOTER刚开源不久，我就能够受邀参加腾讯开源的沙龙分享，感到十分的荣幸。因此，我以开源“小白”的身份，分享我在开源过程中吸取的教训和经验。作为小白，不得不说踩“坑”真的很多，所以教训是放在经验前面的。

克服开源恐惧

以前，在我看来，GitHub只是用来膜拜大神，“借鉴”大神代码，用到自己的项目当中。当然我也尝试把自己写的代码放在GitHub上，但并没有很好地管理它，star只有个位数。我平时写代码的时候，没打算给别人看，只要自己能看懂就行，所以代码风格会比较粗放。我甚至还有“把fork当成star”的黑历史。我的同事实在看不下去了，提醒我：“这样做是会被人笑话的。”

TENCNET SOTER开源不仅是我的个人想法，也是公司层面的考虑。一开始做开源的时候，我是相当恐惧的，毕竟是“小白”，没有经验。但当我逐渐想通了以下几点，就不再惧怕开源了：

开源是每个人都能做的事情
无论大神还是小白，都可以参与到开源当中，开源对任何人都是没有门槛的。小白把自己的代码贡献出去，社区开发者阅读过后，发现问题，进行反馈。对小白来说，开源不一定能得到“膜拜”，但一定能通过反馈优化代码。
不过度在意star数
开源的本质是什么？比较谁的star数更多？Star数少了是不是就很丢人？肯定不是。好的开源项目，star数自然不会少。但如果舍本逐末，在项目质量都得不到保证的前提下就过度追求star数，那才真的很丢人。社区也不会欢迎这样的项目。
给自己信心
这里要感谢下我的leader——kirozhao。从架构到代码，再到文档和演讲，kiro都事无巨细的对我进行指导，有他撑腰，我不再怀疑自己，这是我给自己的信心，更是kiro帮我建立的信心。
开源提倡相互学习，走出舒适区
开源其实相互学习的过程，在微信开源Tinker、Mars等项目时，团队发现开源对微信产品的稳定性和功能丰富起到了很好的反哺作用。知道了这点，“小白”自然也不会惧怕开源了，反而更希望拥抱开源。

项目发布

下面介绍的这些，是我开源前从来没想过的一些问题。这些错误“小白”会犯，甚至是star数不少的开源项目作者也会犯一些错误。下面我们就一起来做几道选择和判断题。

文档是应放在wiki中还是code repo中？
我在整理代码的时候，发现repo中有90%以上都是HTML代码，同事都“嘲笑”我说“就像写了个前端项目”。实际上，我只是把生成的javadoc文件都放在code repo里面，造成了这样的假象。后期，我把一些项目文档，例如License，readme，contributing.md放在repo里面，而更详细的介绍，例如原理、安全接入指南等放在wiki repo 和 git pages里面。这样可以保持repo的清爽。
是否选择合适的代码检查配置？
每个编程语言都有不同的检查规范。代码检查配置，如Java的PMD在编译期间就已经做好，如果检查不通过的话，编译也是不成功的。这是保证自己代码质量的一种方式，不至于闹太大的笑话。
中英文之间是否有空格？
不同的字体有不同的显示，大部分字体中英文之间都不会去做空格处理。但实际上中英文之间有空格，整篇看起来在视觉上会更舒服，不至于太过散乱。
Readme写中文还是英文？
答案是：根据目标用户选择。英文的readme是一定要写的，但中文Readme放在前面还是后面，要根据项目的目标用户决定。比如TENCENT SOTER主要面向国内用户，国外的手机并不支持，因此我们选择把中文放在前面。在中文readme最顶处留一个“for English version”的链接，可直接引到英文的readme介绍。但像WeFlow这些面向全球开发者或设计者的项目，最好中英文都有，实在精力有限也必须保留英文，而且要放在前面。
Readme越简洁越好，还是越详尽越好？
Readme写得太多，会让大家对项目望而却步。最好的做法是，告诉别人你的项目是什么，如果需要详细介绍，可以做链接，引导用户前往wiki或者自己的官网。还有做QuickStart，很明确地告诉用户怎样最简单地去使用我们的项目，给用户传达“噢，原来用你的项目这么简单，我也可以试一下”的信息。正因为“试一试”，你的项目就可能成为别人使用的目标。千万别给用户一种“繁文缛节”的印象。
demo，你选择炫技还是易上手？
如果你的示例代码写得过于复杂的话，同样会让开发者望而却步。用户会觉得“哇，你的项目太高大上，我用不了”“你的代码太复杂，肯定效果不好”，或者开发者会怀疑人生，“是不是我能力不够”。这样你会白白流失一部分用户。