第 2 小节：为开源项目建立良好的基础

2022-08-16
浏览 (687)

第 2 小节：为开源项目建立良好的基础

项目命名的学问

命名对于程序员来说，简直就是编程路上的绊脚石。几乎每一行代码，都深受着类名、变量名、方法名、参数名的折磨。当然，也不是全都无迹可寻。代码中的命名通常可以通过它在上下文中的作用、角色来命名，也可以参考各种设计模式中的习惯命名。

但是，给项目命名的话，其实没有那么多条条框框，我们的思维其实可以再发散一下。

如果是一种开源框架或者类库，可以用明确的功能来命名，如 ORM 类的框架，可以用 *SQL；如对象映射工具，则用 *Mapper；日志工具，则用 *Log……

但是如果我们的项目是一款开源产品，就需要用既有辨识度又能让人易于记忆的名称了。那怎么能让人易于记忆呢？

我个人的建议是反向利用联想记忆法，从项目的功能或者特点出发，联想到有一些关联又特别的名称。可以从影视作品、文学作品、游戏作品等取材，因为这些作品往往充满想象，拥有丰富的人物、事物设定。特别是从一些深受欢迎，传播深远的作品中获取灵感。一个典型的案例是 Python，它的原意为蟒蛇，源于它的创始人龟叔（Guido van Rossum）很喜欢的英国 20 世纪 70 年代首播的电视喜剧《蒙提·派森的飞行马戏团》（Monty Python’s Flying Circus）。

另外，朗朗上口的名称也会让人跟容易记忆。这可能有关语言学，但是很多成功的项目表明，使用双音节，辅音+元音，会有很好的效果！

再缩小范围，就是技术群体喜欢的科幻、魔幻作品，比如星球大战、漫威、哈利波特、迪士尼等等。我尝试在下面列出一些已有的和我想到的例子：

项目名称	项目类型	原意
Azkaban	工作流	哈利波特中的一所监狱
Tars	RPC 框架和配套平台	「星际穿越」中的机器人
ZooKeeper	分布式服务注册和治理	动物园管理员
Elsa-workflow	工作流	冰雪奇缘公主
Tomcat	Web 服务管理器	经典的汤姆猫
SkyWalking	观察性分析、应用性能管理	天空行走，非常形象

相比还有很多优秀的项目，都有这种让人过目不忘的名称，欢迎继续补充。

如何打造一个优秀的 README

README 应该包含哪些内容：

项目名称
项目 LOGO：可以设计一张中意的图片，也可以通过 Patorjk 生成你想要的字符画。当然，如果你愿意的话自己手写设计一个也是一个不错的主意；
多语言切换：推荐中英切换链接展现，在项目根目录建立 README.md 以及 README-ZH.md，若以中文为主则为 README-EN.md 文件。不论您的文档以什么语言为主，我们都建议您将多语言切换的超链接或者按钮将其放置在文档较为顶部或者比较明显的地方（或者您也可以为它单独列出一个标题并将它放在下面）；
项目勋章/挂件（Badge）：这是一个很好玩的东西并且可以增加项目趣味性，可以通过 Shields 进行生成你想要的 Badge 进行展现；
项目背景：项目背景很简单，就是你为什么做这个项目，动机和背景是什么；
项目特点：项目的核心价值，对比同类型项目的优势以及项目自身的特点是什么；
安装：如何进行项目的安装；
使用：如何使用该项目，这里如果使用方式简单可以直接写进 README 中如果较为复杂则引入文档链接地址进行指引；
项目参与者：该项目的参与人展现，可以借助 OpenCollective 进行贡献者信息展示。
讨论与反馈：文档以及项目官网指引，项目沟通渠道如 QQ 群，公众号，TG 群/频道，项目社区等地址；
项目打赏方式：国内微信，支付宝，还可以使用 Gitee 一键接入打赏，国外常用的有 PayPal, OpenCollective；
参与贡献方式：指引开发者们如何参与到项目中协同完善整个开源项目；
开源协议：开源协议类型指引。

也可以参考成熟的开源项目以及同类型开源项目中的 README 的内容。

为项目撰写文档

项目文档是开源项目非常重要的一个部分，很多开发者会根据项目文档来决定是否使用或学习该项目，并且非常关注项目文档的入门部分。

项目文档应该包含哪些内容：

项目简介：项目名称、背景、特点等。
快速入门：安装、入门示例、典型示例、常见问题解答等。
基础指南：各模块使用说明、旧版本迁移指南等。
进阶指南：架构设计说明、高级用法等。
技术博客：知识普及、使用技巧、性能对比、应用案例等。
技术支持：线上社区（如微信群、QQ 群、钉钉群、微博、公众号、TG 群/频道(可配置 bot 持续跟进项目进度)等）、线下交流会、培训、视频、推荐书籍及博客等。
版本发布计划：制定版本发布时间表，规划项目的未来发展方向等。
国际化：面向全球开发者的项目需要支持多国语言的项目文档。

这里有一些工具和服务可以帮助你生成一个文档网站：

开源项目的代码质量要求

一个认真打造的开源项目，肯定是希望有其他用户来使用，更希望有更多外部贡献者能参与进来的。那么评价一个开源项目好不好，代码的质量就是非常重要的衡量指标了。

代码质量是程序员的基本功，说到这个话题，首先自然是需要去翻阅经典的专著了，《重构》、《设计模式》、《代码整洁之道》是程序员必备的手边书。

除了基本功之外，我们还需要保证代码的规范，比如命名、目录结构等。因为开源项目需要迎接来自世界各地的贡献者贡献的代码，为了保证代码的整体风格一致性，那么让贡献者共同遵守一个规范就非常有必要了。

代码规范一般都可以参考每个语言的官方规范，并借助静态检查、代码编辑器插件、lints 等工具，如常见的 EditorConfig、StyleCop、tslint、style lint 等等，在每个 Pull Request 时都先进行编码风格检查。

说到规范，还有就是进行 Git 分布式协作时的规范，如分支命名规范、Commit Message 规范、Issue 模板、Pull Request 模板等等。把这些都拟定起来后，这个项目看起来就很正规、很美观。

而一个开源项目的质量，除了代码本身以外，更重要的是整个项目的状态。

第一点，这个项目必须编译通过。我们可以通过 CI（Continuous Integration 持续集成）来把每次合并后的代码编译一遍，把编译状态通过 Badge 来展示，常见 CI 工具有 Travis CI 和 Jenkins。

第二点，就是运行状况。是否能正常运行也是最基本的检查点了，有条件的话最好是通过 CI/CD 来把 Demo 站点运行起来。有一个可让用户即时尝试的 Demo，对开源项目的成功是非常有帮助的。

第三点，就是单元测试覆盖率。覆盖率是对开源项目质量考察的标配的指标。覆盖率的检查可以通过集成 CodeCov 来做。它可以在每个 PR 中检查合并后对覆盖率的影响，合并后可以分析项目当前覆盖率，并可以用 Badge 来展示。同时，单元测试也对每个 PR 提出更高要求，必须全部通过了才给予合并。

第四点，就是外部贡献者数量。可能你会很奇怪，为什么我要把贡献者数量列进来？那是因为，他们对你这个项目的兴趣已经高到了会研究代码、并会贡献代码了，就能间接地说明这个项目的质量是有一定的分量的。他们愿意把它做得更好！

第五点，生产案例。开源项目大多数是业余时间进行开发的，本身没有企业支持。那么，当它们被真正用于企业生产环境，并带来收益了，才说明这个项目是真正对用户有价值的。所以，开源项目可以收集一下用户的生产案例，一方面可以鼓励开源贡献者的付出，另一方面又可以展现这个项目的价值，还能对企业进行一定的宣传，这是三赢。

第六点，代码的注释。开源项目有一个很大的特点就是任何人都可以自愿为其在符合开源协议的情况下进行二次开发或者为其贡献出自己的代码，因此您所写出的应有较高的可读性以避免在他人想要进行贡献时因为代码的阅读产生障碍。所以一个好的开源项目应具有完善的代码注释，这也同样是一个良好的开发习惯，我们也有应理由相信我们能够做在这方面的更好！