lua-users home
lua-l archive

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

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.