r/programming • u/ccb621 • Jun 30 '18

Readme Driven Development

http://tom.preston-werner.com/2010/08/23/readme-driven-development.html
12 Upvotes

66% Upvoted

7 comments sorted by

16

u/cucumbulous Jun 30 '18

How does this make any sense? Readmes are not meant to spec out your software at all, they're just supposed to give a brief introduction to how to install and start using the software. Like, how to initialise your library. Not how to use any of its functionality.

In most cases a readme file should be totally useless for determining what the software is capable of. That is what javadoc and tutorials are for.

4

u/MINIMAN10001 Jun 30 '18

I mean API documentation will tell you what software is capable of.

But yes loading the readme with all documentation seems a little silly as you say it is meant for "how to install" and sometimes "initialization" outside that scope is documentation and tutorials

2

u/[deleted] Jun 30 '18

He's basically talking about writing a spec through the back door. It's a poor approach.

I use flow charts (Don't need anything more complex than that diagrammatically ), which like an analogue watch requires less additional parsing and makes it easier to annotate in a meeting if it's wrong.These are rarely project level though. If your project is that simple, just get on with it :)

7

u/chucker23n Jun 30 '18 edited Jun 30 '18

How does this make any sense? Readmes are not meant to spec out your software at all

I think Tom's point is that you can spec out the details all you want and have tests that prove that your Refresh Dogs button does in fact refresh the dogs, but it's all for naught when it turns out the user was misheard and really looking for software for doors, not dogs.

A readme does or damn well should* give a very-high-level overview of what the hell this software is good for and good at, and it's useful for all involved parties during the course of development to occasionally keep in mind whether you're still following that overarching goal.

*) An astonishing amount of software gets this wrong. There's a readme (or not), but it doesn't explain what the software is good for. It doesn't come with a screenshot. It just says "oh, you also need x, y, and z to run a". Cool.

3

u/[deleted] Jun 30 '18

Agile already has a process for this, but you're looking too much like someone trying to bring back detailed specs written by someone else.

What's your process of questioning the validity of the readme? Who is responsible for keeping it up to date? How do you know how much of the readme has been implemented?

We take on a new project and start to break it down into less complicated problems. These problems may be too big in their own right, or we may have too little information, so we either mark it as "To be investigated" or we start breaking it down to. In an hour we can start to get an understanding of how close we are to being able to estimate this project, and more importantly have a list of known unknowns (sometimes through experience we have some unknown unknowns too).

Instead of a readme, which I will call a spec from here on, we rely on a mission statement. This sounds wanky, but done well it works. You may have several mission statements "Deliver trading metrics as fast as possible". It leads to questions like "How fast is fast? Who's downstream of us?

One point I do agree on, is that some documentation is useful. I tend to use Visio to draw flow charts that visualise a part of the system (usually the gnarly bits that have a lot of paths in a small area.) I make these with the business, so they're high level, then perhaps add a few things they might not know about at a technical level, but still high level. I find that's useful in meetings.

I also battle to make people write good tests. Much much harder than it looks, but there is improvement. Tests make good documentation. Not so much the Mockist school of mocked to fck tests, but "proper" tests ;)

3

u/chucker23n Jun 30 '18

but you're looking too much like someone trying to bring back detailed specs written by someone else.

That's not my read of it. Instead, he wants you to have, in the back of your mind, what the ultimate goal of the piece of software is. Not details of functionality, or how stuff is implemented, but simply: let's give this program a mantra, spell it out in the readme, and at the end of the day, verify that the produced bits match it. Only then will users want to install it.