<div dir="ltr">From a best-practices point of view, I have found the following efforts helpful. <div>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.</div><div>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.</div><div>-behavior only specifies the type of object being used but not the human context around this. </div><div>3. Layering of Code: - Code when written , must separate data-access API and Data-representation functions.  </div><div>   Code like lists:flatmap( fun (abc) -> ; (xyz)->  end , [ some_list ] )   should only be seen at the lowest levels. </div><div>  The higher-level code should always look like  </div><div>   NewObjectState = my_action_on_my_business_object( ObjectState ). </div><div>   Folks who want to understand how the module works from a business-logic point of view, may read the higher-layers of code. </div><div>4. Tools like Cscope , Code-Bubbles, Source-Graph may help the reader understand the Call-graphs. </div><div>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. </div><div><br></div><div>cheers</div><div>sachin </div><div><br></div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Apr 27, 2016 at 8:52 PM, Richard A. O'Keefe <span dir="ltr"><<a href="mailto:ok@cs.otago.ac.nz" target="_blank">ok@cs.otago.ac.nz</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">I've been thinking for some time of writing a paper with the<br>
title "Why can't I see the structure?" based on the idea that<br>
modules in every programming language I know look like blobs.<br>
I'm aware of visual notations like UML, BON, SDL, and what<br>
was it, Visual Erlang?  But for me, those are just spaghetti<br>
with meatballs; once you get beyond just a handful of boxes<br>
in your diagram, all diagrams look much the same.  In any<br>
case, I'm interested in the medium scale.<br>
<br>
Why can't I see the structure in a 3000-line module, or even<br>
a 1000-line module?  (I am not asserting that Erlang is<br>
particularly bad here.  It isn't.)<br>
<br>
The kind of structure I'm interested in can, I think, be<br>
described as *rhetorical* structure, like relationships<br>
between paragraphs.<br>
<br>
My *belief* is that if this structure were made explicit,<br>
perhaps by textual structure, perhaps by annotations, perhaps<br>
by some graphical form (but probably derived from annotations),<br>
it would be easier to understand medium-sized wodges of code.<br>
<br>
I'm aware of annotation support in languages like Java and C#<br>
and for that matter, Smalltalk, but with the exception of<br>
Smalltalk, nobody seems to be using annotations in this way<br>
(and that exception is me).<br>
<br>
I'd be very interested in hearing from anyone else who has been<br>
thinking in this area.<br>
<br>
<br>
_______________________________________________<br>
erlang-questions mailing list<br>
<a href="mailto:erlang-questions@erlang.org" target="_blank">erlang-questions@erlang.org</a><br>
<a href="http://erlang.org/mailman/listinfo/erlang-questions" rel="noreferrer" target="_blank">http://erlang.org/mailman/listinfo/erlang-questions</a><br>
</blockquote></div><br></div>