lua-users home
lua-l archive

[Date Prev][Date Next][Thread Prev][Thread Next] [Date Index] [Thread Index]

On 20/12/2011 8.31, Axel Kittenberger wrote:
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

Sorry, but probably I wasn't clear about that: I'm completely with you on this point (that's also why I invested some time to give a small contribution for beta-testing Steve Donovan's ldoc). Doc comments IMO *are* part of the code, since they put upfront the contract any function/class/whatever will obey to. It's part of the interface to the client code (especially for those languages that have no way to specify it more formally *in* the code proper).

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.

Just for the archives: this is a reply to another message in this thread. The citation above is not from me.

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,

Yes, that's the bare minimum for doc comments