[Date Prev][Date Next][Thread Prev][Thread Next]
- Subject: Re: Lua code learning path using annotated source by Steve Donovan
- From: Georg Lehner <jorge-lua@...>
- Date: Tue, 20 Dec 2011 06:12:26 +0100
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
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 -
much more verbose then the source code.
While I have seldom used annotated source code, I loved to have it available
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