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

[Vlad Dumitrescu]

Hi!

On Thu, Apr 28, 2016 at 8:16 AM, Richard A. O'Keefe <ok@REDACTED>
wrote:

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

What kind of annotations do you have in mind?

For me, there are two main kinds of code complexity that need explanations:
static and dynamic.

The static one refers to the way functions call each other and can be
mitigated by using small functions that do just one thing and by naming
them in a meaningful way. Then a cross-referencing tool can connect the
dots and produce a useful description of the structure. Annotations could
help even further by providing a bit of "why"-knowledge. My feeling is that
the same reason that makes naming functions difficult might make writing
useful annotations just as difficult.

The dynamic complexity is harder to tame, though. It's about run-time
interactions that are best described by message diagrams, protocol
descriptions and the like. (Often, the interactions are inter-modular too,
but maybe this is not the meso-level you want to document?) I can't see
what kind of annotations in the code would help here, except in toy-level
examples. For me, this is the part that is usually most difficult to
understand when reading code.

best regards,
Vlad
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160428/8e761f60/attachment.htm>