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

[Richard A. O'Keefe]

On 28/04/16 5:04 PM, Gergely Buday wrote:
> I  am not sure if it matters for you but how about Standard ML modules?
Suffice it to say that I've been well aware of ML for a long time and have
the latest release of SML/NJ installed on my desktop and laptop machines
for a reason, think that SML's structures and functors are the bee's knees,
and no, they *don't* help with *this* issue one little bit.

Don't believe me?
Try finding your way around /usr/local/smlnj/ckit/src/ast/build-ast.sml
(all 3105 lines of it) without a native guide.

OK, so build-ast.sml is something of an extreme case: nearly half of the
lines of code in ckit/src/ast/ are in that one file.  And I'm sure there's
good reason for that.

There are other rather large modules in the SML/NJ distribution.
Even fairly small modules can have the same problem, where you're
just presented with a list of blobs (although blobs with types are
somewhat easier to make sense of) all looking pretty similar.

When I say that "modules in EVERY programming language I know look
like blobs", that includes languages I *like* and *esteem*, and it
certainly includes languages with nested modules.

People are getting sort of OK at commenting single functions.
They've got the idea about providing comments for an entire module.
But with the single exception of Smalltalk, nobody seems to do anything
about meso-scale structures.  And Smalltalk just classifies the methods
of a class into groups.  For example, in Pharo the methods for
SequenceableCollection are categorised as
  - accessing
  - comparing
  - converting
  - copying
  - enumerating      (iteration, to you)
  - private
  - removing
  - shuffling
  - sorting
  - splitjoin
  - testing
and then a bunch of
  * extensions for package so-and-so
and the categories are partly well defined and partly ad hoc.

But the *relations* between the methods are not stated.  (For examples,
methods in the private category exist to support methods that are public.
My Smalltalk annotations already let me express that, but I suspect that
"support" isn't a simple concept.)