Date: Tue, 9 Dec 1997 19:58:26 +0100 From: Eivind Eklund <eivind@yes.no> To: Charles Henrich <henrich@crh.cl.msu.edu> Cc: perhaps@yes.no, freebsd-current@freebsd.org Subject: Re: VM system info Message-ID: <19971209195826.64951@follo.net> In-Reply-To: <199712091643.LAA04851@crh.cl.msu.edu>; from Charles Henrich on Tue, Dec 09, 1997 at 11:43:31AM -0500 References: <66jnt0$ddh$1@msunews.cl.msu.edu> <199712091643.LAA04851@crh.cl.msu.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, Dec 09, 1997 at 11:43:31AM -0500, Charles Henrich wrote:
> In lists.freebsd.current you write:
>
> >(4) Code is not commented. If necessary, the function comment can
> > contain a reference to external documentation that explain the
> > code. This should only happen for core functionality that can't
> > be be implemented simply; in other cases, either drop the
> > functionality or re-implement until it is simple. If something is
> > so complex that it needs external documentation, it had better be
> > non-changing.
>
> YUCK! All code should be commented! Just to make things entirely
> clear, just because the author things this code "is so simple,
> everyone must understand it" does not make it so.
If you read carefully, you'd have found that there were quite a few
other rules about commenting. Have you ever tried reading code where
variables are clearly documented? It is _way_ easier to read than
code that is directly documented.
"Say it in code; comment if you can't." That "can't" is fairly rare.
> >(5) Code prerequisites is documented through assert() or similar
> > functionality.
>
> Egads! I wish assert() was thrown down to the pits of hell. Its a
> programmers cop out. In almost no circumstance does one ever need to assert.
> If you find an error condition, COPE as best you can! Especially in the
> kernel.
There are four ways to cope:
(1) Ignore error; return OK, even though the function failed to do
it's job.
(2) Return error code
(3) Throw an exception of some sort, e.g. longjmp().
(4) panic(), a la assert().
I'm arguing that when there is a BUG in your program, the correct
answer is (4), possibly as a combination with (3) or (2).
Why? You're already dealing with a buggy system. There is no chance
in hell that you caller 'know how to deal with the error' - the error
is an error of program structure, and a routine isn't supposed to know
how to deal with errors from calls that can't fail.
If you argue that this is an exceptional case just like a file not
being present, and should be handled the same way - I disagree. A
complicated and sloppy system has a much higher risk of being buggy
than a small and rigidly defined system which trap all errors as soon
as possible.
The assertions are part of the definition of the system. They are a
technique to get that rigid definition, the one that create an error
when the system would otherwise behave outside the specs - to allow
you to actually limit the system to behave exactly inside spec.
This isn't laziness - it is the way to create robust, correct systems.
Eivind.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19971209195826.64951>