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

[Joe Armstrong]

On Tue, May 3, 2016 at 3:29 AM, Richard A. O'Keefe <ok@REDACTED> wrote:
> 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."

YES ^ 100

A slight modification:

You need to explain the code that isn't there that somebody "versed in the
art might reasonably expect to be there but was not"


>
> 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.

I think the blind alleys need documenting. I add comments
like:

   " The obvious approach of doing XXX fails because YYY so don't go there"

Most of my projects have a directories called 'research' and
'dustbin' they are huge compared to the final program - I don't
commit or publish them.

In particular research can be huge with PDF specs, etc one line of
which has ended up in the code.

The BIG question the documentation should answer is
not what does this code do, or how does it work but "how did the person
write the code" ie what were the thought processes necessary to write the
code.

Cheers



>
> 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.
>
>
>
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions