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

[Richard A. O'Keefe]

On 3/05/16 7:19 PM, Vlad Dumitrescu wrote:
>
> This is true and would be useful, but I think I can see a problem 
> (which might very well be the reason why it isn't something people 
> already do): after a while, there will be literally thousands of 
> discarded stuff. How am I supposed to search and find the alternative 
> that works, especially if I am now working on a different problem than 
> 6 months ago when the stuff was originally written? Is this search 
> faster than starting from scratch? IMHO the answer is that what needs 
> to be saved is a higher-level description, not a complete brain dump 
> of the process.

I think Joe Armstrong has already answered this, and with my mention of 
version control
I thought I had addressed it.  The answer is that we should keep a lot 
more about the
history of a program than we (specifically including me in that) do, but 
that it does not
have to go in the source file.

I think we agree that when you are trying to put out fires in the 
current code base,
you want to read as little as you safely can, and you don't want to be 
distracted
by stuff that doesn't seem to be relevant.  But when you have decided on 
a fix,
that's when you need to review the history to see if someone already 
thought of
it and rejected it for good reason.

I'm reminded of an anecdote I read about the Knuth-Morris-Pratt string 
searching
algorithm.  (At least, that's what I think it was.)  It got built into a 
particular
text editor.  A few years later one of the authors was called in and 
told "your
string search algorithm isn't working.  Fix it."  It turned out that a 
succession
of programmers had looked at the code, thought it was broken, and 
"fixed" it,
and all that had to be done to *really* fix it was to put the old code back.

I'm not as good as Joe Armstrong (though I'd like to be).  In some of my 
projects
I keep a directory dead.d.  Code that seemed like a good idea at the 
time, and may
still have value as a source of ideas, or at least as an (explained) 
dreadful warning,
goes there.  For a file foobar.src I often keep a file foobar.txt with 
musings about
what might or might not go in foobar.src, criticisms of what other 
people have done
to explain why I am not going to do that, thoughts about refactoring, &c.

I'm not sure that a brain dump of the whole process would be a bad thing,
as long as you don't *have* to read through it to see the present source 
code.
>
> There is also a difference between what is interesting for teaching 
> people (beginners) and what is interesting for future reference for 
> the team that develops the code.
I used to have large chunks of the Discworld stories memorised.
The story I have in mind at the moment is the contest between Granny
Weatherwax (who would be the leader of the witches in the Ramtops
if Discworld witches had leaders, but they don't, so everyone just _knows_)
and a new witch called, if memory serves me, Diamanda Tockley.
GW's friend Nanny Ogg is acting as GW's second.

Nanny Ogg [thinks] one day you're going to lose.
Diamanda: What level are you on?
Granny Weatherwax: Level one.
Diamanda [nastily]: Just beginning?
Granny Weatherwax.  Yes.  Every day.  Just beginning.
Nanny Ogg [thinks] but it's not going to be today.

Tell it not in Gath, but I am now 60, and have been programming since
about 16.  Every day, just beginning.  I'm just gone through the Swift
book and need to do a lot of exercises.  People are telling me I need
to learn Pony because it's the latest and greatest.  (I've had the Pony
compiler on my laptop for *months* and still haven't written a program
with it yet.)  Other people are telling me I need to understand the
Ambient calculus, and I'm really annoyed with myself because I can see
that it's *very* closely related to some consulting I did about 10 years
ago and it would have been really useful to know back then.  Oh, and
I've been re-learning a language I last used about 1984, and am starting
to feel fluent in it again.

Yet if you sit me down in front of a body of code, a project, then I am
a *total* newbie all over again.  With respect to the *programming
language*, I'm not a beginner.  With respect to the *project*, I really am.
I've been converting some F# code to Smalltalk (and greatly improving it
while doing so, if I may say so, boast boast).  And some Python code,
also to Smalltalk, which Python code turns out to have a *massive* errata
list on the web, despite having been published by a previously reputable
publisher) so I'm having to rely much more on the textual description
than the actual code.  I feel very much like a beginner struggling with new
stuff, except that this is bigger.

As a specific example, sit me down in front of the Cowboy source code
and I'm clueless.  NOT because it's bad -- I carefully chose an example
that isn't -- but because it's a big chunk of code that I am not 
familiar with.
I'm not a beginner with *Erlang* but I'm a beginner with *Cowboy*.
I need all the help I can get.
> These categories need different levels of detail, different kind of 
> information.
(a) I am not sure that the categories are all that distinct, and
(b) absolutely.  (I'm reminded of the tracing facilities in Arthur Norman's
symbolic integration program, my first introduction to serious logging.)

Adequate documentation tools let you annotate a chunk of text with
the level it's appropriate for (like the black or white page corners in
Wheeler Thorne and Misner's "Gravity", marking out basic and advanced
sections, where it looks like I'm *never* going to cope with the advanced
sections).  Good documentation tools make it easy for you to view a
document with only the material appropriate to you visible.

One more anecdote.  When I joined Quintus, I was handed a ring binder
and told "this is the internal documentation.  It will help you find your
way around the code."  I promptly got lost and couldn't find a
certain file.  "Oh, we forgot to tell you.  It's out of date.  Half of it is
wrong.  We didn't bother keeping it up to date because we knew that
stuff anyway."