[LRUG] Your Code is My Hell

[Daniel Barlow]

On Fri, Aug 26, 2011 at 11:09 AM, Glenn Gillen <glenn at rubypond.com> wrote:
> How could we make it better?

Ah, the key question :-)

> I have a feeling that python does better but I've no real experience to support it. I wonder if the the "Readme Driven Development" approach would be better, especially for gems. All of my thoughts are pretty fluffy though and could really use critical appraisal of someone outside both the ruby and x community.

I like the concept behind RDD, but what happens in practice is that
the project evolves, and the code examples get out of sync with what
actually runs, and you start thinking "this README duplicates my test
examples, I need to DRY it out"

One thing that I've observed, from a largely ahistorical perspective,
is that we seem to be in a place where gem authors are using our
standard documentation tool (rdoc) to produce documentation of the
implementation - and then, only the public parts of the implementation
- but that the specification which drove these implementation
decisions is left to sit in a git repo somewhere that Google will
never find it.  Perhaps we need tools that will take our specs and our
code and produce nice HTML (or other format of your choice) and
format them neatly in such a way that you could read through what the
system is supposed to do, with examples from the spec and interpolated
code from the bits of the implementation that implement that spec.  I
know, I know, those who forget literate programming  are condemned to
repeat it.  But it does seem odd that there's no widely-used
{test::unit|rspec|shoulda|wotsa|howabouta|}=>html tool that people
naturally reach for when they want to document their modules.

Or maybe the specs alone are not a suitable master document with which
to introduce the system to a potential user, and there needs to be
some other document which has a more narrative structure.  And then
we're back to a README but this time it's a README with transclusions

Don't take this as a firm prescription: some of it is thinking out
loud, and the rest is just rambling out loud...