[erlang-questions] What I dislike about Erlang

[ok@REDACTED]

> On Fri, Aug 31, 2012 at 11:36 AM, Francesco Mazzoli <f@REDACTED> wrote:
>>
>> Did you read his post?  His main point about documentation is that
>> people tend
>> to document functions but not data structures, which is something that I
>> fully
>> agree with.
>>
>
> This post has nothing to do with erlang. It is just an ancient
> question: waste your time on documenting inner code or not.

Waste?  In this case, code that is basically *good*, written
by a competent Erlang programmer, has a serious performance
limitation --- which may well have been a complete non-issue
in its original context, but now that the code is available
for use in other contexts, may be very important.  And this is
not documented *anywhere*, and it is hard to see in the code
because it is swamped by other things.

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

Nobody said documentation had to be *bulky*.
In my Smalltalk system, I've found that the code changes like
dreams as I refactor and extend it, but that the data structure
invariants are far more stable.  It is precisely the act of
documenting those invariants that makes it *possible* to work
so easily on the code.

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

Perhaps that is why the ffmpeg site says the software
"work really well 99% of the time".  That kind of failure
rate is not tolerated in the Erlang world.

Hmm.  Why am I believing this?  Ad fontes! Calculemus!
Download ffmpeg sources.
Count SLOC:    460,014 lines
Count comments: 77,320 lines (excluding copyright notices & GNU licences)
That's roughly one comment line for every 6 SLOC.
This is *NOT* "sources without any documentation inside them".

Returning to Erlang, I thought I had made the point that
I wanted the structure of the code to reveal what is going
on, but it doesn't.  And for the specific example considered,
10 lines of commentary would have rendered roughly 200 SLOC
of code pretty near superfluous to understanding.