首页 文章 精选 留言 我的

精选列表

搜索[harmonyos开发],共10000篇文章
优秀的个人博客,低调大师

开发工具总结(9)之开源项目的README文档的最全最规范写法

版权声明:本文为博主原创文章,未经博主允许不得转载。https://www.jianshu.com/p/813b70d5b0de 转载请标明出处:https://www.jianshu.com/p/813b70d5b0de 本文出自 AWeiLoveAndroid的博客 【好消息】我的微信公众号正式开通了,关注一下吧! 关注一下我的公众号吧 看过很多开源库,发现有些库的文档写的一团糟,有的甚至就是一个标题,让你自己下载之后运行,自己摸索,看的很头疼。而那些使用量大的库的文档写的很标准,很详细,看的很舒服。 README文档写的好的话能减少很多使用成本,能帮助这个库让更多人了解,更多的人用,可以说好的文档就是一个门面。有好的 README 文档的项目不一定是一个好开源项目,但一个好开源项目一定有一个好的 README。 下面就简单的总结一下README文档规范写法。(这只是我个人根据github上几百个大型开源库总结出来的,如你有更好的意见,欢迎留言。) 一、README文档的组成部分 看过很多开源框架的README文档,综合一下,大概有以下几部分组成: (一)国际化 (二)项目工程介绍 (三)项目的使用效果图 (四)项目特点 (五)项目的基本结构(架构) (六)集成方式 (七)使用方法 (八)混淆 (九)关于作者/组织及交流方式等信息。 (十)贡献者/贡献组织 (十一)鸣谢 (十二)版权信息 二、下面就每个部分简单的分析一下: (一)国际化 github是面向全球的一个开源网站,所以不要局限于中文文档,建议写一个英文的README,让来自全球的人都能更方便的了解你的项目。推荐写法,在REAMDE开头写上国际化引用地址: 比如: 国际化 (二)项目工程介绍 项目介绍是必不可少的,它能让别人快速了解项目。项目介绍主要包括: 项目名称、logo(没有logo就不写) 这个开源项目是做什么的? 这个项目是什么语言编写的? 这个项目目前被多少人用到了,有多少好评等? 项目维护、依赖更新状态(如果有的话,这也可以用)等 项目可用版本及其他版本,以及每个版本的更新信息记录 Demo 或官网地址(如果有) 效果图如下所示: 英文版: 英文版项目介绍 中文版: 中文版项目介绍 上述案例里面那些图标,请参考这个网站 Shields.io,打开之后想用哪个直接复制就可以了,同时它也支持自定义样式。 (三) 项目的使用效果图 如果是一些自定义控件或者项目的演示效果的,基本都会放上演示效果图,可以是图片,也可以是gif图。 建议:静态的页面的放截图,交互很复杂的建议放gif图。 如果功能比较多,建议每个功能一张效果图。 示例如下: LoveHeartView使用示意图如下图所示: (四)项目特点 主要是介绍项目的特点,方便别人查看和了解该项目。 比如 360的RePlugin框架的特点就写的很详细: 360的RePlugin的项目特点 (五)项目的基本结构(架构) 这里主要介绍项目的各个组成部分,如果是框架,可以附带架构图解;如果是其他的,可以提供一些UML分析图,顺便分析一下源码也行的。 比如 360的RePlugin架构图解 如下所示: 360的RePlugin架构图解 关于RePlugin架构的相关说明 (六)集成方式 一般的项目传到jcenter上面或者AS插件传到jetbrains的话 一般会附带相关的集成方式的说明。(如果没有这些措施的话,这一步可以略过不看。) 比如 okhttp 就有详细的3种集成方式: 一个是下载Jar包;一个是引用Maven库;第三个是添加Gradle依赖: okhttp的集成方式 (七)使用方法 一般的README必不可少的,最重要的就是用法,主要包括:安装,运行,编译,部署,debug,该github上的这个库如何在自己的项目中使用,以及需要注意的问题,版本更新适配问题等等。 这里就拿 Glide 举例说明,Glide里面有一个详细的wiki使用文档的,首页的README里面也写了一个简单的基本用法,如下图所示: Glide的基本用法 (八)混淆 一般来说,开源库都会设置一些混淆规则的,部分项目由于项目类型特殊之处,所以就没有混淆这一项,具体的看开源项目来定。 例如LitePal这个开源库的混淆 如下图所示: LitePal混淆规则 (九)关于作者/组织及交流方式等信息。 这个就很灵活了,不是每一个必备,当然写出来方便大家联系作者,也是很好的。可以写一下作者或者组织的联系方式,微信,邮箱,博客,微博,甚至支付宝转账二维码等都是可以放上去的。 例如 blankj的AndroidUtilCode这个库为例,为了避免打广告嫌疑,我做了打码处理: (十)贡献者/贡献组织 比如 谷歌推出的 sample 里面就有贡献者/贡献组织信息,如下图所示: 谷歌推出的sample的贡献者/贡献组织信息 (十一)鸣谢 这个主要是引用了哪些开源技术,这里可以做一些鸣谢,表示对别人的尊重,其实也是一个引用声明,避免因为版权而引起不必要的纠纷。 例如:我写的这个库 https://github.com/AweiLoveAndroid/CommonDevKnowledge/blob/master/interview/summary.md 里面就写了鸣谢。 https://github.com/AweiLoveAndroid/CommonDevKnowledge里面的鸣谢 (十二)版权信息 版本很重要,开源许可证很重要,如果没有生命版权,可能会因为一些侵权行为而无法很好的维权,版权信息可以保护作者的权益(个人理解)。 世界上的开源许可证,大概有上百种。很少有人搞得清楚它们的区别。最流行的有六种:GPL、BSD、MIT、Mozilla、Apache、LGPL 乌克兰程序员Paul Bagwell,画了一张分析图,说明应该怎么选择。这是我见过的最简单的讲解,只用两分钟,你就能搞清楚这 六种许可证之间的最大区别。 六种开源许可证之间的区别 比如 Picasso 里面的版权信息,如下图所示: Picasso 里面的版权信息

资源下载

更多资源
Spring

Spring

Spring框架(Spring Framework)是由Rod Johnson于2002年提出的开源Java企业级应用框架,旨在通过使用JavaBean替代传统EJB实现方式降低企业级编程开发的复杂性。该框架基于简单性、可测试性和松耦合性设计理念,提供核心容器、应用上下文、数据访问集成等模块,支持整合Hibernate、Struts等第三方框架,其适用范围不仅限于服务器端开发,绝大多数Java应用均可从中受益。

Rocky Linux

Rocky Linux

Rocky Linux(中文名:洛基)是由Gregory Kurtzer于2020年12月发起的企业级Linux发行版,作为CentOS稳定版停止维护后与RHEL(Red Hat Enterprise Linux)完全兼容的开源替代方案,由社区拥有并管理,支持x86_64、aarch64等架构。其通过重新编译RHEL源代码提供长期稳定性,采用模块化包装和SELinux安全架构,默认包含GNOME桌面环境及XFS文件系统,支持十年生命周期更新。

Sublime Text

Sublime Text

Sublime Text具有漂亮的用户界面和强大的功能,例如代码缩略图,Python的插件,代码段等。还可自定义键绑定,菜单和工具栏。Sublime Text 的主要功能包括:拼写检查,书签,完整的 Python API , Goto 功能,即时项目切换,多选择,多窗口等等。Sublime Text 是一个跨平台的编辑器,同时支持Windows、Linux、Mac OS X等操作系统。

WebStorm

WebStorm

WebStorm 是jetbrains公司旗下一款JavaScript 开发工具。目前已经被广大中国JS开发者誉为“Web前端开发神器”、“最强大的HTML5编辑器”、“最智能的JavaScript IDE”等。与IntelliJ IDEA同源,继承了IntelliJ IDEA强大的JS部分的功能。

用户登录
用户注册