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

[Lorenzo Donati <lorenzodonatibz@...>]

On 19/12/2011 15.24, Axel Kittenberger wrote:
> > I'm in the process of revamping my C skills and I'd like to study Lua
> > sources as an example of very well-written code using the annotated source
> > by Steve Donovan found at:
>
> "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
> well-written for being small and fast, but I reserve the adjective for
> "very well-written" if it would have universal documenting function
> and file headers (last time I looked, it has in some particular hard
> cases)
I based that judgment on my experience of fiddling with Lua code: 
although I'm no expert C programmer, I was able to understand with 
little effort many (although limited) parts of it, and that allowed me 
also to tweak the source in some points to suite my needs.

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.

I'm no expert of C programming, though, so It may well be that Lua 
sources have less-than-average code docs coverage, but I cannot comment 
on that. OTOH several times I've seen Lua code praised on this list for 
its good organization and readability.

As for annotations: well-written code may not need annotations to be 
understood by an average programmer, but for a beginner annotations may 
save hours of head-scratching.

> Other than this, I would study code in the domain you intend to be
> projecting on.

Thank you for the good advice. I would certainly do so, if I were to 
tackle some specific problem domain.

I work as a teacher now, and this school year I'm teaching basic C to 
youngsters (age ~16). My current skills are more than enough to cope 
with toy programs and exercises, but I'm taking the chance to improve my 
knowledge of more advanced C programming techniques (but still 
general-purpose), so any good corpus of code will do. Using Lua source 
for the task has the added advantage of improving my knowledge of my 
favourite language (which is not C ;-)

> So if you want to code a parser, virtual machine,
> garbage collector or the like, it is a good idea to look at Lua code,
> if you want to eventually do something else like 3D animation or such,
> you should inspect code of that domain instead.

Cheers!

-- Lorenzo