Quotes of the week - all about documentation [LWN.net]

For some reason, the act of typing in some kerneldoc makes people's brains turn off. Perhaps it's because "oh, I am supposed to type some documentation here" instead of "gee, I think this code is unclear, let's clarify that".

-- Andrew Morton

I personally don't like kerneldoc at all, because the truth is that people will work on fixing bugs and other useful things before keeping kerneldoc up to date. And that's the basic fact which cannot be denied.

I wish it could work, but it doesn't across the board. So unless we have dedicated monkeys scouring over every single patch that goes into the tree and doing the necessary kerneldoc updates, kerneldoc will be chronically wrong somewhere.

That leads to confusion and lost developer time. Because if the kerneldoc bits are wrong, it's worthless.

-- David Miller

I expect better: You never see me hard with time word making sentence coherent stuff. Ever.

-- Rusty Russell

As usual: You shall never rely on the source code comments, they will only mislead you.

-- Manfred Spraul

to post comments

Quotes of the week - all about documentation

Posted Dec 11, 2008 11:43 UTC (Thu) by hppnq (guest, #14462) [Link] (15 responses)

It keeps amazing me that intelligent, cooperating people can't see the value of documenting what needs to be documented. Without it we would still be carving kernel code in cave walls.

Quotes of the week - all about documentation

Posted Dec 11, 2008 11:58 UTC (Thu) by etienne_lorrain@yahoo.fr (guest, #38022) [Link] (5 responses)

What is more important, when the developper has limited time: to document the bug or to fix the bug and test the fix?
Same, what is the first thing to do: fix the problem and test the solution or change the comment in the source?
Now _that_ would be different if the user who finds a bug documents it, and the developper reads the document and fix the bug; but when are user writing documentation? Most of the time they do not even want to read the FAQ...

I probably had a bad coffee this morning...

Quotes of the week - all about documentation

Posted Dec 11, 2008 13:11 UTC (Thu) by tpo (subscriber, #25713) [Link]

What's more important: to do it right or to do it somehow?

Demagogy++

Quotes of the week - all about documentation

Posted Dec 11, 2008 18:02 UTC (Thu) by faramir (subscriber, #2327) [Link] (2 responses)

Bug? What does 'bug' have to do with documentation? Bugs go in bug tracking system (which seem to be pretty rarely used by kernel developers as well). Documentation is what describes how something WORKS, not how it DOESN'T WORK. When code/doc is out of sync then there is a bug which goes into the rarely used bug tracking system and hopefully something gets changed eventually to to put them back in sync.

Should people really have to read the GLIBC code in order to figure out how to use printf() for their first "hello world" program? Why should I have to (potentially) read all of the kernel source in order to write a device driver? Not documenting standard support routines is likely to result in MORE bugs in code that uses it as developers misunderstand the intricacies of how to use those functions.

Quotes of the week - all about documentation

Posted Dec 12, 2008 1:58 UTC (Fri) by Lumag (subscriber, #22579) [Link] (1 responses)

Is there lots of documentation regarding extending GLIBC? Because there are pages describing kernel <-> user interface (Analogy to printf).

Quotes of the week - all about documentation

Posted Dec 12, 2008 13:55 UTC (Fri) by nix (subscriber, #2304) [Link]

Emphatically no. A lot of glibc's nifty features (LD_AUDIT,
_MALLOC_PERTURB, a lot of others) don't seem to be documented *anywhere*.
A good few (e.g. the asychronous resolver) aren't described in the glibc
manual but only in pdfs on Ulrich's homepage (the first place anyone would
think to look, although Google saves you there).

Quotes of the week - all about documentation

Posted Dec 13, 2008 22:47 UTC (Sat) by dirtyepic (guest, #30178) [Link]

the real bug is that you don't consider changing the code and leaving the comment untouched a bug.

Quotes of the week - all about documentation

Posted Dec 11, 2008 18:35 UTC (Thu) by iabervon (subscriber, #722) [Link] (5 responses)

I think the common issue is that people document things that don't need to be documented until they burn out on doing useless work, and finally get to something that needs to be documented and don't document it.

The reality is that almost all code, most functions, and some variables don't need to be documented. Many cases of needing documentation are actually maintainability flaws (i.e., people who don't read the documentation, which is most people most of the time, will write code with bugs). And it's important to avoid providing obvious documentation, because it makes it harder to realize that something is actually tricky. But there's a tendency to strive for completeness and then fail in arbitrary ways.

Of course, the best documentation is generally not written by the author of the code, but by the first person to have problems understanding it and then figure it out.

Quotes of the week - all about documentation

Posted Dec 11, 2008 21:44 UTC (Thu) by stijn (subscriber, #570) [Link] (2 responses)

Seconded, with some additional thoughts. I often write code initially with few comments, pertaining to design or gotchas or ideas for improvement where necessary. Then when I go in a few months later and try to find the logic behind it all, because a bug needs fixing or functionality added, or because the code needs to be generally modularized and sanitized, I usually add much more extensive documentation. It helps at that point to be both the author of the code and to experience puzzlement. As a method (not suitable for all projects) it works quite well for me, although I would rather not submit the result as a good example of how to document code. Still, I think the best annotation comes from a second pass over the code, by someone not actively working on it. This might explain its scarcity. I also think that good documentation largely describes data structures, their invariants, the range of states they may assume, and what bits of code do to achieve transformations and maintain invariants. Don't show flowcharts ..

Quotes of the week - all about documentation

Posted Dec 11, 2008 22:22 UTC (Thu) by marduk (guest, #3831) [Link] (1 responses)

That works until you write something and then immediately get put on another project or part of the code, then someone else gets your code and makes more undocumented changes and again and again. Eventually your code comes back your way and you're like... wtf?

Quotes of the week - all about documentation

Posted Dec 12, 2008 10:25 UTC (Fri) by stijn (subscriber, #570) [Link]

It was merely an observation. Additionally, your scenario was already included in my description. If I am the second developer getting the first developer's code, I would definitely add comments as I went in. So, I am advocating this as a good habit to follow at a personal level rather than as project documentation guidelines.

Quotes of the week - all about documentation

Posted Dec 12, 2008 17:51 UTC (Fri) by hppnq (guest, #14462) [Link]

Some projects of course have very strict guidelines as to what is accepted in code and comments. I don't think that these are counterproductive, in general. From what I remember about the Apache code -- we're talking 1999 here ;-) -- every routine was nicely documented at the top but the code did not have too many comments interspersed. It worked like a charm, I think, and many projects utilize a similar strategy.

I think the documentation effort should be geared more towards such a situation than one in which each bit of code is properly documented: that is, indeed, quite a waste of time and energy. It can never be wrong to document what a well-defined part of a bigger picture does (so this should be the rule), whereas documenting bits and pieces has to be indicative of problems in the code (so this should be the exception). I would therefore say that maintainers have a special interest and responsibility when it comes to documentation.

Quotes of the week - all about documentation

Posted Dec 12, 2008 20:00 UTC (Fri) by droundy (guest, #4559) [Link]

Of course, the best documentation is generally not written by the author of the code, but by the first person to have problems understanding it and then figure it out.

And the worst documentation is written by the first person have problems understanding the code, and try to figure it out, but fail... which I've seen happen on more than one occasion with code I wrote. :(

Quotes of the week - all about documentation

Posted Dec 12, 2008 19:35 UTC (Fri) by giraffedata (guest, #1954) [Link] (2 responses)

It keeps amazing me that intelligent, cooperating people can't see the value of documenting what needs to be documented.

That used to amaze me until I finally came to the conclusion that lots of people just don't think like me. The first time I was criticized for having too many comments in my code started me toward that realization, and noticing that C is the preferred language for describing a code change on mailing lists such as LKML solidified it.

I can't read C worth a damn. I can read a paragraph of English in a tenth of the time and frustration as the equivalent screen of C. I'm so useless with C that I never review C code -- it would be a waste of time, though I'm happy to review an English description of a code change. But many times I've sent a description of a code change along with prototype code and the response made it obvious the reader didn't or couldn't read the description and just looked at the code.

There are ways to write even C so it reads so much like English that comments are largely superfluous. But the C code we're talking about isn't that -- it's code written as instructions for a computer.

Quotes of the week - all about documentation

Posted Dec 18, 2008 12:33 UTC (Thu) by spiv (guest, #9031) [Link] (1 responses)

It depends on the change. English doesn't always communicate more clearly than C. Some code can be most concisely expressed in actual code, because sometimes it's the precise details of exactly what the code is that matters.

With some other code its difficult to reverse engineer the intent from the code, so English is better.

And then there's the distinction between a comment in the code, explaining why the code is the way it is, and a comment describing a change to the code. Sometimes the purpose of a change is self-evident from the diff, sometimes a change needs a "cover letter" to explain it. And commit-by-commit messages are different from summaries of a bunch of commits intended to be merged as one.

In summary: it's not one-size-fits-all. Like writing, you should consider your audience. Think about how you're delivering code for review, and adjust your delivery accordingly. Write a high-level, plain English summary if that's called for. Or just make sure the diff updates all the relevant comments if that's all that's needed. Or draw diagrams! And so on...

Quotes of the week - all about documentation

Posted Dec 19, 2008 2:51 UTC (Fri) by giraffedata (guest, #1954) [Link]

I can't read C worth a damn. I can read a paragraph of English in a tenth of the time and frustration as the equivalent screen of C. I'm so useless with C that I never review C code -- it would be a waste of time, though I'm happy to review an English description of a code change.
It depends on the change. English doesn't always communicate more clearly than C. Some code can be most concisely expressed in actual code, because sometimes it's the precise details of exactly what the code is that matters.

Yeah, but my point is that it also depends on the brain. It's clear to me that for many people, there are far more cases where C communicates more clearly than English than for me.

What I haven't figured out is if they've trained themselves to think that way, or self-selected themselves from a special group, because I know that the brain is fundamentally not wired to work anything like a Von Neumann machine and it should be pretty hard for the average person to read algorithms (which is what a typical C program expresses).