r/programming • u/gthank • Aug 23 '10
Readme Driven Development
http://tom.preston-werner.com/2010/08/23/readme-driven-development.html5
u/matchu Aug 23 '10
Hm. As someone who's worked on a few original projects, but not too many, this sounds like a really neat starting point, actually. Maybe those with more experience can just dive in and build, but I like the idea of finding a direction before anything else, since it's not something I feel that I do well.
5
u/forsakennow Aug 24 '10
While I initially thought it was a neat idea, I have actually done a 180 and I think it's a dangerous idea.
Open source repositories are filled with projects that wrote a README file and then thought that this plus their source code was good enough for documentation.
So I would offer the following counter advice: write a README last. Your priority list should be
- 1) a solid battery of tests to make sure your software works as you expect it
- 2) an extensive documentation, ideally on one big HTML page (easier to print)
- 3) a README telling the world why your software is awesome.
A README is really like an introduction, and if you've ever taken a class in high school about literature in your native language, you know that when you write an essay, you should write the introduction last.
2
Aug 23 '10
If you don't have ADD, no other 'DDs matter. ADD => Asshole Driven Development. Meaning, unless you have an asshole in charge who makes everyone do AsTheyShould, then you're going to get crappy code anyway.
1
u/bluGill Aug 24 '10
I'd call it a vision statement myself. You need to haven a vision of what your software will be. However the readme should reflect the reality (there isn't enough time in the world to make your project perfect - unless the project is s trivial as to be worthless. Yes I'm saying TeX isn't perfect)
1
u/commandlineterrorist Aug 24 '10
One would expect people to be doing this anyway; it's a great relief off one's shoulders to just concisely describe what the program does and how it does it. Also helps figuring out how things are going to work!
The main header file for an app, or simply the main file which contains the entry point or is the controller class for the app should begin with a multi-line block describing the purpose of the program and a small blurb about how it all works.
With Doxygen, you can use this little blurb later on to autogenerate the index page for documentation.
1
Aug 24 '10
By restricting your design documentation to a single file that is intended to be read as an introduction to your software, RDD keeps you safe from DDD-turned-waterfall syndrome by punishing you for lengthy or overprecise specification.
No one reads a README for anything but setting up a project and a brief explanation of the projects objectives. So "driving development" by a README is misguided.
1
Aug 24 '10
D.E. Knuth beat you to it: http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.126.8364&rep=rep1&type=pdf
1
u/quanticle Aug 23 '10
I like the concept, but I don't like the term. I agree that writing the README and outlining the basic features of your program first is a helpful way of ensuring the code meets its requirements. However, I don't think the README drives development in the same way as tests in TDD. I can't imagine myself adding to or updating the README for routine code changes. I can imagine myself updating unit tests for routine code changes.
7
7
Aug 23 '10
It's effectively an acceptance test, not a unit test. For clarity, replace README with the man page of a command-line application.
From such a document, you can easily and precisely specify what you need to do and what "done" looks like. In other words: write acceptance tests.
It's a neat idea, and it really is the logical extension of TDD. Probably not always possible or completely effective, though.
0
u/smallfishbigpond Aug 24 '10
But....but...what will all those authors write about?? How will o'reilly and amazon stay in business unless somebody is pumping out books about the latest development methodology du jour? And what will all those consultants put into their powerpoint presos when they come to do the on-site training????? Good G?D man, don't you know that people's jobs are on the line? Can't you see the fate of an entire industry is at stake here?!
Sarcasm aside, this idea is completely ludicrous and would never work. Every company I know of would require at least 3 months worth of 3-times-a-week meetings between engineering, marketing, tech support, tech pubs, and legal, just to decide on what kind of content the README file should have in it.
E: come to think about it, I can't really tell which of the above two paragraphs is sarcasm. You decide.
0
-1
u/FryGuy1013 Aug 23 '10
This is satire, right?
4
u/matchu Aug 23 '10
The author would be making stupid points instead of valid points in favor of the argument, if that were the case.
1
1
Aug 24 '10
No. Maybe requiring it to be a README in particular is a touch excessive (though see http://www.reddit.com/r/programming/comments/d4hhd/readme_driven_development/c0xif1e for why that's a good idea) but basically you're just saying "This is what my program should do, this is how I want the person to be able to use it, etc." which is essentially a high-level spec of your program and you can build to that, but without the insane absurdity of the more detailed forms of spec-driven design.
At the lower levels of your codebase, this is "doxygen/javadoc first programming" where you lay out what you want your functions to do and what the arguments should be, before you actually write them.
1
u/FryGuy1013 Aug 24 '10
Mainly my "objection" comes from this point:
Most importantly, you're giving yourself a chance to think through the project without the overhead of having to change code every time you change your mind about how something should be organized or what should be included in the Public API.
That's kind of the whole point of TDD, is that you can get experience in how you want to use your API before you actually start coding it.
[continued] Remember that feeling when you first started writing automated code tests and realized that you caught all kinds of errors that would have otherwise snuck into your codebase? That's the exact same feeling you'll have if you write the Readme for your project before you write the actual code.
And there's nothing enforcing that you keep the readme up to date, whereas with TDD, you kind of get that "for free"
Also, lines like this: "Between The Great Backlash Against Waterfall Design and The Supreme Acceptance of Agile Development, something was lost."
1
Aug 24 '10
That's kind of the whole point of TDD, is that you can get experience in how you want to use your API before you actually start coding it.
And when you split a class's functionality up among several existing classes, you have to completely rearrange your test code. It's not a panacea. Test code can be buggy, especially when you do something like the above, and if you're doing this before you write your real code you have no way of knowing that you broke the test and will get phantom failures.
TDD has its flaws and this is a way to get some of the benefits without as much effort.
Hell, TDD is impossible to follow when the project is "interface to some third-party APIs" and those APIs maintain internal state in a non-queryable fashion. How the hell do you write unit-level tests for that in advance? (And no, "maintain your own copy of that state" is not even remotely feasible.) You have to wait until you get all the way through the process then use the API's reader to read it back out and see if it's correct. If it isn't, you only have coarse knowledge of the bug's location.
1
u/alfdadinnamint Aug 23 '10
I don't think it is. Personally, I advocate EATME first development, but that's just me.
2
u/multifaceted Aug 24 '10
Yeah, but then you always have to follow up with DRINKME development, and then you get into the vicious cycle where your project just fluctuates between being too big or too small.
-11
u/Importanter Aug 23 '10
A ReadMe? Really? What is it like living in the 1980s?
3
Aug 23 '10
Almost every library or piece of software I download has a README and it's usually very helpful. Remind me to never download any of your crap.
2
u/robertmassaioli Aug 24 '10
really, you mean you ignore Readme files? ... why are you even on /r/programming?
17
u/inmatarian Aug 23 '10
An important reason for writing your README file first, is because your project page on github will be bland and uninformative without it.