[erlang-questions] What I dislike about Erlang

[Francesco Mazzoli]

At Fri, 31 Aug 2012 11:57:53 +0400,
Max Lapshin wrote:
> This post has nothing to do with erlang. It is just an ancient question: waste
> your time on documenting inner code or not.

Again, did you read the post?

  It's well known that there are two kinds of documentation, "external"
  documentation for people writing clients of a module, and "internal"
  documentation for people maintaining the module itself.  It's also well known
  that the division is simplistic; if the external documentation is silent about
  material points you have to read the internal documentation.

The "internal" documentation, as you call it, is the only one that really
matter.  It's no waste of time.  It rarely happens that after using a library
for more than I few hours I don't need to look at the code to understand what
the functions I'm using do.

Moreover, as ROK says, I really don't see the distinction: the "internal" and
"external" documentation should be one.

> I never document such things, because it is silly: you spend more time on
> rewriting documentation.

I'd much rater have something that explains the internal design that some edoc
that tells me more or less what functions will do.


> And I perfectly read ffmpeg sources without any documentation inside them.

Well, some code is pretty self explanatory.  But most code isn't.

--
Francesco * Often in error, never in doubt