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

[Richard A. O'Keefe]

On 28/04/16 5:09 PM, Flavius Aspra wrote:
>
> Do you have any real-life example where complex stuff do not look like 
> blobs?
>
Literate programs.  I'm thinking of the book about LCC, where I never 
felt lost
at all.
>
> I'd start with this.
>

Unfortunately, while literate programs help a lot, they do so by throwing
a *lot* of text at the problem, and still don't make relationships other 
than
"mentions" really explicit.  The major problem with literate programming
is that it's not happening.  At *best* people are writing stuff like 
JavaDoc,
and while that isn't too bad at describing interfaces that are just piles of
procedures, it's useless for someone trying to maintain a Java class,
because it encourages you not to write about hidden methods and there's
no way to describe the relationships between the methods, so people are
in effect being trained NOT to write the stuff I need to read.

I'm hoping that comparatively lightweight annotations that could be
exploited by an IDE (at least in principle) are something programmers
might be willing to use.  Even me!