[erlang-questions] dialyzer output help

[Garrett Smith]

Hi Roelof,

My two cents of this style of docs...

> %% doc Function which controls the programm.
> %% First the shape is asked on the user.
> %% After that if a valid shape is entered the dimensions
> %% are asked , and if they are valid the area is being calculated.
>
> collect_data() ->
>     Shape = shape_from_user(),
>     {X, Y} = dimensions_from_user(Shape),
>     geom:area(Shape, X, Y).

I would actually document this function this way:

 collect_data() ->
     Shape = shape_from_user(),
     {X, Y} = dimensions_from_user(Shape),
     geom:area(Shape, X, Y).

This is very clear, at least to me. The upside is that it's also
consistent with the code, every time, guaranteed!

Your instructors may require that you "document your code" but consider this:

  %% Set Name
  Name = "Roelof"

Sure, it looks absurd, but if you're required to "document your code"
what else are you going to write there?

Documenting functions that are completely obvious by restating the
same code in another language inside a comment block is, well, see my
last sentence.

Of course if your function isn't obvious, commenting may help you come
to an understanding of what you actually want to write. Take that
learning, make the function obvious, then delete the comment!

Skip pedantic restating of function implementations.

Documenting user facing functions, on the other hand, is important to
help your users understand how to use a function. It doesn't
necessarily cover each and every implementation detail - for that you
can always read the code - but it should provide what a user needs to
use the function as it was intended to be used.

I use edoc [1] to generate user docs for modules - I don't know if
there's something new that folks are using these days. Anyone?

Btw, 'collect_data' here is the wrong name for that function IMO as
it's result is an area, rather than data used to calc an area.
collect_data might look like this:

 collect_data() ->
     Shape = shape_from_user(),
     Dimensions = dimensions_from_user(Shape),
     {Shape, Dimensions}.

Then maybe to highlight the user input + calc operation:

  area_from_user() ->
      {Shape, Dimensions} = collect_data(),
      area(Shape, Dimensions).

  area(Shape, {X, Y}) ->
      geom:area(Shape, X, Y).

Back to comments - my point is that your *code* is the docs, as far as
implementation. If your code is not clear, make it clear. If you can't
make it clear, try harder. There are some very rare cases where some
code is just hard and some comments can help clarify what's going on -
but these are *unicorn rare* in my experience.

I realize that you're just picking up a new language here and that's
plenty to worry about, short of all this (my) religiosity - and I
applaud you for pressing ahead to learn Erlang - great job! I'm
picking on some things here that are common vestiges of imperative
style programming (and possibly teaching) in order to showcase what I
consider some serious benefits of Erlang (and
functional/declarative/good programming in general).

Garrett

[1] http://www.erlang.org/doc/apps/edoc/chapter.html