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

[Sachin Panemangalore]

>From a best-practices point of view, I have found the following efforts
helpful.
1. Dialyzer Annotations : - Types in function definitions or when accessing
elements from a collection help big-time to build context of  'what' to
expect from a particular data-structure . In absence of this you  need to
go back and forth between functions which write to a collection and
functions which are reading from a collection. In Erlang , dialyzer
annotations help to add this at the function head level . I would say , its
a Must to define custom type names in annotations  "term()" or "any()"
should rarely if any be used.
2. Human readable comments at the top of the file help the user to impart
context of the ensuing logic to the reader. The internal logic may change
based on implementation , but the purpose for the existence of the file
rarely changes.
-behavior only specifies the type of object being used but not the human
context around this.
3. Layering of Code: - Code when written , must separate data-access API
and Data-representation functions.
   Code like lists:flatmap( fun (abc) -> ; (xyz)->  end , [ some_list ] )
should only be seen at the lowest levels.
  The higher-level code should always look like
   NewObjectState = my_action_on_my_business_object( ObjectState ).
   Folks who want to understand how the module works from a business-logic
point of view, may read the higher-layers of code.
4. Tools like Cscope , Code-Bubbles, Source-Graph may help the reader
understand the Call-graphs.
5. Comments on Concise Code : As the developer gains more expertise in
functional programming , the developer writes more and more concise code ,
for he has moved on from being a developer to an artist. Concise is
beautiful.  But this also brings about a moral duty for the artist  to add
comments for the 'tricky parts' , which will help other developers bridge
the gap and appreciate the beauty.

cheers
sachin



On Wed, Apr 27, 2016 at 8:52 PM, Richard A. O'Keefe <ok@REDACTED>
wrote:

> 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.
>
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160501/b795d593/attachment.htm>