lkml.org 
[lkml]   [2008]   [Dec]   [1]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [RESEND][PATCH] Add /proc/mempool to display mempool usage


On Tue, 2 Dec 2008, Pekka Enberg wrote:
>
> OK, but why do we have those different ABI "stages" in
> Documentation/ABI then? The README file there seems to contradict what
> you say. Or maybe I'm reading it wrong...

I think that whole Documentation/ABI stuff is utter tosh, and should just
be thrown out, whenever it talks about interfaces that are _not_ ABI's.

IOW, it's fine to document things that are actually supposed to be stable,
but:

- assuming that non-documentation means that it's not an ABI is bogus
and wrong.

- explicitly documenting something as "not an ABI" is wrongheaded and
stupid, because it's meaningless and only sets people up for being
disappointed later.

So yeah, I think we might as well remove the "testing" one. Right now it
can act in two ways:

- as documentation on how to use it (ie as "stable").

This is fine, but then it shouldn't be called "testing", should it?

- as an excuse for whining later when it _did_ get used, and people break
exported ABI's, and we need to revert the breakage.

And this is the one that I don't think is valid. No amount of
documentation will ever make something less stable.

So as far as I'm concerned, "testing" should either go away (as a way to
discourage people from even _knowing_ about the things, and hoping that
they never get used), or it should be moved to "stable".

And in the end, nothing is ever totally black-and-white or quite that
simple, but that's the mindset you should have.

Finally, when it comes to documentation as a bigger issue:

- wrong documentation is irrelevant. It doesn't matter if the
documentation says "X", when the code does "Y".

If people rely on "Y", then pointing at the docs and saying "but you
should never have relied on it, because teh docs say X" is totally and
utterly bogus. The _documentation_ was wrong. Don't ever use incorrect
documentation as an excuse.

Too many people seem to think that documentation is the "final" argument.
It's not. Not even close. It's a hint and a help, but it's _secondary_ to
code. Anybody who doesn't understand that should never be allowed to write
code (or documentation, for that matte).

[ The same is true of assert()'s in code too - I've seen too many damn
asserts that were simply _wrong_, and then when they triggered, people
would always blindly assume that the assert() was right, and try to
change the code to suit. For some reason people have a hard time asking
themselves whether perhaps the bug was in the assertion itself. ]

Linus


\
 
 \ /
  Last update: 2008-12-02 03:59    [W:0.092 / U:1.812 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site