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

[Georg Lehner <jorge-lua@...>]

On 12/19/11 15:24, Axel Kittenberger wrote:
> "Very well-written" code would be commented inline and not need
> annotation. Yeh, sorry about being provocative about this, but I keep
> insisting that good coding is also good documenting. So maybe its
>    
I have found in practice, that source code has different audiences
with different scopes of perception and different needs of information 
volume.

In my environment I like it best, when source code is "self documenting"
and needs only small amounts of inline comments - just enough to explain
unexpected features, exceptions to usual conventions or maintenance 
hints and the like.

We write API's which are used by our customers (internal and external) 
and these of
course require a completely different type and style of documentation - 
normally
much more verbose then the source code.

While I have seldom used annotated source code, I loved to have it available
when needed.

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.

Regards,

    Jorge-León