Re: [RFC] Bug zapper? :)

[Bernd Eckenfels]

In article <4118E78F.8070301@xxxxxxxxxxx> you wrote:
> I guess it should describe INPUT, OUTPUT, PROCESS, STATE CHANGE, and 
> ERRORS :/

You do not need to describe behaviour if the pre-condition is not valid. 
This is common asumption in "design by contract". However, this is not good
robust programming, to not handle those pre-condition violations.

> Readable.  Don't guess what the code does.

What else is the author of the comment doing? You cant describe all
(important) aspects of a piece of code in a language that is less complex
than the code itself (locking, concurrency, mm, ressouce consumption, ...).
In fact you are very likely introducing errors. Thats why comments are only
needed for navigating you and giving you the overall picture. They are also
good to explain unusual statements (especially in optimized hot path).

> Of course not.  The goal I was aiming for was to create an extremely 
> structured documentation scheme in the hopes that it would provide a 
> great deal of ease in understanding what a function does.  "if you don't 
> understand what it does, don't fuck with my code"

Well, actually it is good to describe a function at the high level, but dont
go further than that.

Greetings
Bernd
-- 
eckes privat - http://www.eckes.org/
Project Freefire - http://www.freefire.org/
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/