Re: Lua code learning path using annotated source by Steve Donovan

[Axel Kittenberger <axkibe@...>]

> I strongly agree that good documentation is a fundamental part of
> programming, but self-documenting code is IMHO the base of good
> documentation, and Lua code (to the extent I have delved into it by now)
> seems quite self-documenting.

Thats so an overused cliche and use. Yes, every semi-talented coder
can parse with dedication through any but the most obscurity contest
code. There are a few functions and file names where the name itself
is really already explains so well what the function/file does, that
no further comment is necessary. Working with your own code you often
don't need it, but when trying to understand others code, a simple
line of human text over every function makes that says what this
function does makes it so much easier, especially for files. You open
a flie and bam! tons of code, and you don't even know what its all
about! Yes for a function I can parse the code, and a few minutes
later, I know what it does. But if it writes (This function is for
this and that) and I only need to know it as reference, cause I try to
understand another part of the code simply made from minutes into
seconds.

> Shouldn't there be at a minimum twice as much lines of documentation then
> lines of code for a good program?  - but then - please be it not inline comments.

And this is the straw-man argument. Twice as much? Never talked about
it. Thats the thing many use argument not to comment:
i = i + 1 -- increment i by 1.
Yes its senseless, but its overdone and lame excuse to not doing
anything. A simple single line of english on the head every function
and every file is all I ask for a code to be "very well written", and
please *BE* that inline comments! A single line of english for every
file bloats no code, and a single line for every function neither,