Have you ever started a project full of excitement, only to find yourself tangled in a web of confusing code and unclear APIs? You're not alone.

What if I told you there's a secret method that top developers use to create better APIs and smoother projects - a method you're probably not using?

Today I'm going to share with you a little-known technique for better API design: README-Driven Development (RDD).

What is README-Driven Development (RDD)?

So, what exactly is RDD?

It's simple: you write a README before you write any code.

In this README, you describe the API of your code. You write it as if the code, the REST API, the package, the framework - whatever you're building - already exists.

Then, you share your README with your coworkers for job-related projects or with friends for side projects, so they can provide feedback. You improve the README based on their input. Repeat this process until everyone is happy with the API and all possible edge cases have been addressed.

RDD often goes hand-in-hand with Test-Driven Development (TDD). You capture your API in your tests, and then you write the code to make those tests pass.

Here's how it works:

1. Write the API in the README as if it already exists.
2. Get feedback from your coworkers and implement it.
3. Capture the API by writing tests.
4. Write the code to make the tests pass.

Why RDD?

RDD has a ton of benefits:

• Design First Approach: It forces you to think about the inputs and the outputs first. By focusing on the API upfront, you prevent implementation details from leaking into your API design.
• Early Feedback Loop: Writing out the API first lets your coworkers critique it and discuss technical design implications. The goal is to come up with an API that offers the best developer experience.
• Clarity of Purpose: RDD helps to define the purpose and scope of the project from the start. This clarity reduces bugs caused by a misunderstanding of the feature being built. It can also prevent scope creep, keeping the project focused on its intended goals.
• Avoids Redundant Work: By solidifying the API upfront, you can avoid the redundant work of rewriting code to change the API later, when changes can be more costly and complex. When you think about all edge cases early, you can avoid unnecessary rework.
• Better Documentation: By focusing on the README first, you ensure that documentation is NOT an afterthought but a core part of the development process. This leads to better, more comprehensive documentation that benefits users and maintainers.
• Onboarding Efficiency: A well-documented codebase with a clear README makes it easier for new team members to understand the project quickly, significantly reducing the onboarding time.
• Enables Parallelization: When you write the documentation first, teams can work in parallel because everyone knows what to expect from each other.

In other words, RDD aligns closely with a fundamental principle in software development:

"Program to an interface, not an implementation." - Gang of Four

What To Include In The README?

Include everything that a normal README would include:

• Features: List the features of your project. Write down why you're creating it and what problems you're solving. This helps users - and yourself - understand what the project should be able to do. Based on these features, you can plan your API.
• Installation Instructions: Include how to install your package or library. If your module depends on other packages, list the dependencies.
• Usage Examples: Show how to use your package or library and what configuration options are available.
• API Documentation: Include the API of your package or library. Make sure you cover common use cases. This is similar to the usage examples but helps you think about the API from different perspectives, like the user and the developer.
• Contributing: Explain how to contribute to your package or library. When working on an internal development team, you can capture or challenge existing development processes.
• License: Include the license of your package or library.

RDD Example

Let's look at an example.

Suppose you want to create a simple package that allows you to generate random integers.

Step 1: Write the README

First, you capture what your project should do and what problems its features solve.

Random Integer Generator

Generate random integers with ease.

Features

• Generate random integers between any two numbers.
• No external dependencies.

Once you figured out what you want to do, you want to show your users how they get started and how they can use your project. So, include the missing sections like installation instructions, usage examples, API documentation, contributing, and license.

Installation

npm install random-integer-generator

Usage

import generateRandomInteger from "random-integer-generator";

const randomNumber = generateRandomInteger(10, 50);
console.log(randomNumber); // Outputs a number between 10 and 50

API

generateRandomInteger(options)

• min (number): The minimum value (inclusive).
• max (number): The maximum value (inclusive).
• Returns: A random integer between min and max.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License.

Step 2: Get Feedback

Now, let's say you take your README to your coworkers so they can critique it. Your coworkers point out a few ways to improve the random integer generator:

• You should be able to call the generateRandomInteger function without arguments.
• It should have a default range of 0 to 100.
• It should take named parameters using an options object.
• Lastly, it should be a named export, so you can easily add more functions in the future.

You agree with your coworkers and update the README.

Step 3: Write the Tests

Now, it's time to create your project so you can write some code.

mkdir random-integer-generator
cd random-integer-generator
npm init -y

Then, install your testing library of choice. In this case, we will use Vitest.

npm install vitest --save-dev

Step 4: Write the Code to Make the Tests Pass

Finally, implement the code that fulfills the README and passes the tests.

export const randomInteger = ({ min = 0, max = 100 } = {}) =>
  Math.floor(Math.random() * (max - min + 1)) + min;

When To Use RDD?

RDD can be helpful in these scenarios:

1. When there's a complex API that you need to get right, usually used by many stakeholders.
   • Open Source Projects: When you're working on a team and want to offer something as open source. For example, an SDK that connects to the service you're building.
   • Internal Libraries: If you're building an internal tool that will be used by multiple teams in your company.
   • Complex Subsystems: When working on an app or service where multiple components interact.
2. When large cross-functional teams need to work in parallel, and you want to make sure one team isn't blocked by another.

Trade-offs

Yes, writing the README and asking teammates for feedback can make the process initially slower than regular development. However, RDD offers a high return on investment under the right circumstances.

When working solo, RDD may add little value if you’re already using TDD.

Be Careful of Scope Creep

Once you have your README for your dream API, focus on the core functionality for version 1, and plan to add additional features in future releases.

Why You're Not Using RDD

Many developers skip RDD because:

• They've Never Heard of It: It's less widely discussed than other methodologies.
• Eager to Code: The excitement of coding can overshadow planning.

Now that you're in on the secret, you know when and how you can use RDD to build better APIs and drive more successful projects. Before you start your next project, launch a new feature, or create a new library, take a moment to write the README first. It might feel a bit unusual at first, but the benefits are substantial.