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

[Richard A. O'Keefe]

I've been thinking for some time of writing a paper with the
title "Why can't I see the structure?" based on the idea that
modules in every programming language I know look like blobs.
I'm aware of visual notations like UML, BON, SDL, and what
was it, Visual Erlang?  But for me, those are just spaghetti
with meatballs; once you get beyond just a handful of boxes
in your diagram, all diagrams look much the same.  In any
case, I'm interested in the medium scale.

Why can't I see the structure in a 3000-line module, or even
a 1000-line module?  (I am not asserting that Erlang is
particularly bad here.  It isn't.)

The kind of structure I'm interested in can, I think, be
described as *rhetorical* structure, like relationships
between paragraphs.

My *belief* is that if this structure were made explicit,
perhaps by textual structure, perhaps by annotations, perhaps
by some graphical form (but probably derived from annotations),
it would be easier to understand medium-sized wodges of code.

I'm aware of annotation support in languages like Java and C#
and for that matter, Smalltalk, but with the exception of
Smalltalk, nobody seems to be using annotations in this way
(and that exception is me).

I'd be very interested in hearing from anyone else who has been
thinking in this area.