同步操作将从 Gitee Community/开源指北 强制同步,此操作会覆盖自 Fork 仓库以来所做的任何修改,且无法恢复!!!
确定后同步将在后台操作,完成时将刷新页面,请耐心等待。
命名对于程序员来说,简直就是编程路上的绊脚石。几乎每一行代码,都深受着类名、变量名、方法名、参数名的折磨。当然,也不是全都无迹可寻。代码中的命名通常可以通过它在上下文中的作用、角色来命名,也可以参考各种设计模式中的习惯命名。
但是,给项目命名的话,其实没有那么多条条框框,我们的思维其实可以再发散一下。
如果是一种开源框架或者类库,可以用明确的功能来命名,如 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.md
以及 README-ZH.md
,若以中文为主则为 README-EN.md
文件。不论您的文档以什么语言为主,我们都建议您将多语言切换的超链接或者按钮将其放置在文档较为顶部或者比较明显的地方(或者您也可以为它单独列出一个标题并将它放在下面);也可以参考成熟的开源项目以及同类型开源项目中的 README 的内容。
项目文档是开源项目非常重要的一个部分,很多开发者会根据项目文档来决定是否使用或学习该项目,并且非常关注项目文档的入门部分。
项目文档应该包含哪些内容:
这里有一些工具和服务可以帮助你生成一个文档网站:
一个认真打造的开源项目,肯定是希望有其他用户来使用,更希望有更多外部贡献者能参与进来的。那么评价一个开源项目好不好,代码的质量就是非常重要的衡量指标了。
代码质量是程序员的基本功,说到这个话题,首先自然是需要去翻阅经典的专著了,《重构》、《设计模式》、《代码整洁之道》是程序员必备的手边书。
除了基本功之外,我们还需要保证代码的规范,比如命名、目录结构等。因为开源项目需要迎接来自世界各地的贡献者贡献的代码,为了保证代码的整体风格一致性,那么让贡献者共同遵守一个规范就非常有必要了。
代码规范一般都可以参考每个语言的官方规范,并借助静态检查、代码编辑器插件、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 提出更高要求,必须全部通过了才给予合并。
第四点,就是外部贡献者数量。可能你会很奇怪,为什么我要把贡献者数量列进来?那是因为,他们对你这个项目的兴趣已经高到了会研究代码、并会贡献代码了,就能间接地说明这个项目的质量是有一定的分量的。他们愿意把它做得更好!
第五点,生产案例。开源项目大多数是业余时间进行开发的,本身没有企业支持。那么,当它们被真正用于企业生产环境,并带来收益了,才说明这个项目是真正对用户有价值的。所以,开源项目可以收集一下用户的生产案例,一方面可以鼓励开源贡献者的付出,另一方面又可以展现这个项目的价值,还能对企业进行一定的宣传,这是三赢。
第六点,代码的注释。开源项目有一个很大的特点就是任何人都可以自愿为其在符合开源协议的情况下进行二次开发或者为其贡献出自己的代码,因此您所写出的应有较高的可读性以避免在他人想要进行贡献时因为代码的阅读产生障碍。所以一个好的开源项目应具有完善的代码注释,这也同样是一个良好的开发习惯,我们也有应理由相信我们能够做在这方面的更好!
JamesYeung、雪山凌狐、ORH、louislivi、itas109、taotieren、沈唁、晓空
发现内容中的错误?还是想要补充更多符合主题的内容?《开源指北》欢迎你进行贡献,点击贡献指南了解贡献的具体步骤。
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。