[erlang-questions] Rhetorical structure of code: Anyone interested in collaborating?

[Richard A. O'Keefe]

There's a grey area.
Today I have to explain documentation to a class,
and one thing I'm going to say is "you need to explain
the code that isn't there."

Example: a function doesn't check an argument.
Why is that code missing?  Because it's checked somewhere else.
If the function is called from a different place, or if the
code that currently calls it is altered, we may need that code
after all.

Example: a function which seems like it should have an inverse
doesn't have one in the code.  Why not?  There's a difference
between "we haven't needed it yet" and "it's not doable".

Example: a function for merging two sets doesn't include any
code to sort them.  Why?  Because it's the caller's job to do
the sorting.

But there's a reason why twists and turns might need recording.
I don't know about you, but more than once I've had the experience that the
'final "right" turn' was actually wrong, and to get working code I've 
had to go
back to something I'd rejected on (what I know see to be) mistaken grounds.

Now that doesn't mean everything has to be in the version we give to the
compiler.  Keeping (possibly wrongly) discarded stuff is the job of the 
version
control system.

And of course an *idea* that is tried in one derivation line and then 
abandoned
may turn out to be very useful for solving a different problem.

For what it's worth, just yesterday I refactored some code.  At the price of
writing one new method I was able to eliminate four others, *and* halve the
amount of storage allocated (and reduce the time).  The old code wasn't
*wrong* exactly.  And the new code is definitely less obvious.  The new
method has a comment

        An earlier implementation of these methods allocated a string
        that was immediately discarded; this creates no garbage.

which explains why the obvious code isn't there.  That's not exactly keeping
an abandoned version, but it does mention that there was one, and why.