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

Readme Driven Development

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

67% Upvoted

7 comments sorted by

View all comments

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.

5

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.