News for hackers. Stuff that matters.
Re:Clean Ruby by sunnyprogram on Thursday December 08, 2011 @02:09AM (#3328104)
I disagree. If you follow test driven development, your tests become your documentation. Want to know what a method does? Look at the tests for the method where it explicitly says what the method is doing and ensures it is functioning correctly.
Re:Clean Ruby by masklinn on Thursday December 08, 2011 @06:03AM (#3328638)
> If you follow test driven development, your tests become your documentation.

That's the shittiest documentation in existence.

Your tests are implementation documentation, they're useful (maybe) for other maintainers, and useless for third-parties trying to actually use your code.

> Want to know what a method does? Look at the tests for the method where it explicitly says what the method is doing and ensures it is functioning correctly.

Right, look at 700 lines of edge cases testing, that's informative and helpful. Not.

Re:Clean Ruby by ollysb on Thursday December 08, 2011 @08:00AM (#3328875)
That's the difference between TDD and BDD, if you're practicing BDD then your tests will be documenting how to use your code, not how it's implementation works.
Re:Clean Ruby by masklinn on Thursday December 08, 2011 @09:29AM (#3329161)
> if you're practicing BDD then your tests will be documenting how to use your code

I'm going to call bullshit on that one all the same.

Re:Clean Ruby by ollysb on Friday December 09, 2011 @10:05AM (#3333908)
This site builds docs for projects based on their integration tests. I think it's a pretty good example of what you can achieve using BDD for documentation, https://www.relishapp.com/myronmarston/vcr
Re:Clean Ruby by masklinn on Friday December 09, 2011 @11:11AM (#3334198)
> I think it's a pretty good example of what you can achieve using BDD for documentation

And as expected, it's awful.

The front page looks good. It's also a Markdown document. Open any actual feature dump[0] and you land straight in dreadful-land. The introduction is acceptably readable (since it's written in markdown throughout), the "code samples" are mostly an unreadable mess with little logical flows and huge blocks of unreadable code. It manages to fail both at being a documentation and at being an APIdoc.

The most laughable part is the "Examples" sections as they show not examples but values with which the placeholders in the rspec test can be replaced.

The only part worth reading of these is the heading, which has nothing to do with RSpec, and the only thing rspec doee is makes this "documentation" worse by imposing the test's structure onto the documentation.

It's not even a step up form having only extracted APIDoc, it's a step down.

[0] https://www.relishapp.com/myronmarston/vcr/docs/cassettes/ca...

Re:Clean Ruby by dextorious on Thursday December 08, 2011 @07:09AM (#3328756)
I hope you don't ever write a library that I would want to use.