> Oliver Xymoron <oxymoron@waste.org> writes:
>
> > Some problems with documentation:
> >
> > - is a poor substitute for code
>
> Unfortunately, code is also a poor substitute for documentation.
In some real sense, the code is perfect documentation. It _is_ complete,
accurate, and uptodate. The problem we have is that it's sometimes not
lucid. Documentation isn't the fix - documentation isn't necessarily any
more clear and doesn't really address the problem. The fix is making the
code more readable, either through restructuring, rewriting, or comments.
You'll note that Linus loves to get 'cleanups'. If the goal is code that
people understand, write understandable code. Code is the soul of a
project, everything else is dead weight.
> > - people read the documentation and fear the code
> > - when people do read the code, they interpret it as suggested by the
> > documentation, missing subtle and not so subtle bugs
> > - fewer people understand the actual code
>
> I don't think the goal is to completely replace reading the code with
> documentation.
I don't think it's the goal either, but it is a major side-effect.
> I think the goal should be to have the documentation serve as an
> introduction to the interfaces. Yes, you'll never understand a piece
> of code as well by reading about it as you will by reading it, but
> you'll get a basic level of knowledge faster and with less effort by
> reading documentation.
The basic level of knowledge stuff can already be bought at your book
store. Linux Kernel Internals, Linux Device Drivers, Design of The Unix
Operating System, etc.
> > - adds more inertia to the interfaces of a system
> > - means changes require a greater investment of effort
>
> I'm not convinced this is bad. There _should_ be some inertia to an
> interface; otherwise, what's the point?
They already have inertia in the form of the work it takes to fix code
that breaks when an interface changes. Why add to that?
Obviously, external interfaces (syscalls, ioctls, /proc) are a different
story. But what we're arguing about now is the internals. Or should the
whole underside of the kernel that modules talk to be declared an external
interface and written in stone? Next you'll want binary compatibility and
we'll be one short step away from having a microkernel.
> > - implicitly promises things won't get changed
> > - broken designs stay broken longer
>
> I'm not sure this is true; documentation can simply mean "this is how
> this works, and this is how it changed since the last version" instead
> of "this is how it works now and always". Mention that interfaces can
> change in the documentation; make sure the reader knows that. Make the
> few relatively unchangeable interfaces loud and obvious exceptions.
This is a straightforward consequence of the investment in documentation.
"Hey, I just wrote this nifty new subsystem and all these docs. Oh look,
there's a nifty way I could improve it by doing <foo> everywhere. But then
I'd have to change the docs. Hell with it."
> > - and we've been doing pretty damn well without it
>
> So? Are you sure we couldn't do better with it?
Umm, yes. Unreadable code is hard to maintain. Documented unreadable code
is not much better - you still have to read the code to fix it and maybe
just to use it. Systematically documenting everything with man pages,
etc., including the readable code (which a lot of the kernel is, happily),
is a step in the wrong direction. Effort is better spent on making the
code comprehensible.
> > I think the informal commentary style of things like
> > Documentation/exceptions.txt is far preferable to any sort of formal
> > function-by-function docs, inline or otherwise.
>
> Unfortunately, even that sort of documentation is often outdated and
> not as useful as it could be. So even if we entirely reject the idea
> of API documentation, it would still be good to try and keep what
> little documentation that we do have up to date.
So next time you spend a couple hours trying to understand something, take
a few notes. Put them inline. Put them in Documentation/. Make a few
simplifying changes. If you see a better way to do it, do it.
-- "Love the dolphins," she advised him. "Write by W.A.S.T.E.."
- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.rutgers.edu Please read the FAQ at http://www.tux.org/lkml/