How to make a good README?

Table of Contents

If you like to share and you make code, you probably have a GitHub, GitLab or other account to share your interesting pieces of code to the world.

Like any Git repo, you’re going to have a README file. And you may not know it yet, but this is perhaps the most important part of your repo.

Beyond your code and its quality, when you share code, it is important that developers who find your code can easily understand what it is about and especially to give them confidence in you, even if they have never seen you before and do not (yet) know your work.

What are the important points to address then?

Dependencies #

Most, if not all, mobile applications have dependencies on other frameworks or libraries. It is important to take them into account for your README, since they may induce limitations or links not desired by the developer using your code.

The platform and the framework #

Let’s start with the most obvious and the one that is mandatory in all cases: platforms and framework.

Let’s take the case of the construction of a Swift Package. This one will contain Swift code created by you in order to facilitate the use of TableViews for example. Therefore your code is directly dependent on UIKit containing the UITableView.

Therefore, your Swift code which until now was universal is only available if UIKit is also universal and therefore on iOS and iPadOS.

It is therefore essential that you indicate in your README three points: UIKit, iOS and iPadOS. These dependencies may prevent another developer from using your code, so you must inform him very quickly to avoid any confusion or problem.

Third-party dependencies #

As well as the platform or system framework used, it is possible that you use a third party dependency. It is also necessary to specify this dependency for several reasons.

The application that will use your code may already use the same dependency but in another version, which can cause problems.

But even worse, the third party dependency have no guarantee of long term support. It is the creator with his community (if it exists) that maintains the existing code. This means that maybe, one day, nobody will be there to fix the bugs or make the necessary evolutions to support the new versions of the system.

It is therefore essential to properly specify these high-risk dependencies.

The tests #

But how to give confidence to other developers? It’s very simple: the quality of your code. And the best way I know for that is simply unit tests!

They are essential to justify the use of your code. They allow anyone to be sure that you have done your work well. In addition, the analysis of unit tests allows you to quickly realize the quality of work and the way a developer works.

They are even more important when the developer’s goal is not to integrate your code but to fork it to make another version.

Add to this the code coverage and you have 2 strong arguments to easily allow the adoption of your code!

The people who trust us #

Let’s not forget that few things have not already been done. So why take your solution rather than the neighbor’s?

The previous chapters are good reasons, but there is even better: the companies / communities / applications that use your code.

If you have companies like Uber or AirBnb embedding your code in their mobile app, it can only help you gain credibility.

So don’t forget to list those actors who believe in you!

The license #

The license of your code is crucial for any developer who would like to use your code. Don’t forget that some of you will want to integrate it in your own code to share, others in their personal application and finally companies may need it for products they want to sell.

It’s up to you to specify the right license. If you are on GitHub, you can directly choose a license when creating your Git repo. This will create a LICENSE.md file at the root of your repo.

Here is a reminder of the most used licenses:

If you have trouble choosing the most suitable license for your situation, here is a very good site with all the information you need: https://choosealicense.com/licenses/

Badges #

We have seen a lot of points that are important. But there is still one that, despite the little space it takes in your readme, I think is crucial: the badges.

They don’t take up space, they are simple and sober but allow a clear and simple message to be conveyed to everyone.

I recommend to put them at the beginning of your README so that they serve as a summary of your repo. Developers will be grateful to you for this since they allow you not to linger too long on a repo that is not suitable.

If you want to know more about badges and how to generate them, I invite you to go to this site: https://shields.io/

Overall body #

Here is the body of your README in a nutshell:

Title and image
Badges (build, unit tests, code coverage, platforms, …)
Current version
Requirements
Features
Installation
Getting Started
Change logs
Contribute
License

Of course this may change depending on the type of code you share. The “Installation” section is very useful when you share a Swift Package or a Cocoapods but not at all for a sample code.

Good examples in my opinion #

Rather than continuing to list the things that need to be addressed, let’s look at what others are doing that I think is right:

I hope this article will have more for you! Do not hesitate to share it and leave a comment!