Quotes of the week - all about documentation
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.
Posted Dec 11, 2008 11:43 UTC (Thu)
by hppnq (guest, #14462)
[Link] (15 responses)
Posted Dec 11, 2008 11:58 UTC (Thu)
by etienne_lorrain@yahoo.fr (guest, #38022)
[Link] (5 responses)
I probably had a bad coffee this morning...
Posted Dec 11, 2008 13:11 UTC (Thu)
by tpo (subscriber, #25713)
[Link]
Demagogy++
Posted Dec 11, 2008 18:02 UTC (Thu)
by faramir (subscriber, #2327)
[Link] (2 responses)
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.
Posted Dec 12, 2008 1:58 UTC (Fri)
by Lumag (subscriber, #22579)
[Link] (1 responses)
Posted Dec 12, 2008 13:55 UTC (Fri)
by nix (subscriber, #2304)
[Link]
Posted Dec 13, 2008 22:47 UTC (Sat)
by dirtyepic (guest, #30178)
[Link]
Posted Dec 11, 2008 18:35 UTC (Thu)
by iabervon (subscriber, #722)
[Link] (5 responses)
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.
Posted Dec 11, 2008 21:44 UTC (Thu)
by stijn (subscriber, #570)
[Link] (2 responses)
Posted Dec 11, 2008 22:22 UTC (Thu)
by marduk (subscriber, #3831)
[Link] (1 responses)
Posted Dec 12, 2008 10:25 UTC (Fri)
by stijn (subscriber, #570)
[Link]
Posted Dec 12, 2008 17:51 UTC (Fri)
by hppnq (guest, #14462)
[Link]
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.
Posted Dec 12, 2008 20:00 UTC (Fri)
by droundy (subscriber, #4559)
[Link]
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. :(
Posted Dec 12, 2008 19:35 UTC (Fri)
by giraffedata (guest, #1954)
[Link] (2 responses)
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.
Posted Dec 18, 2008 12:33 UTC (Thu)
by spiv (guest, #9031)
[Link] (1 responses)
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. 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...
Posted Dec 19, 2008 2:51 UTC (Fri)
by giraffedata (guest, #1954)
[Link]
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).
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
Quotes of the week - all about documentation
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...
Quotes of the week - all about documentation
Quotes of the week - all about documentation
Quotes of the week - all about documentation
Quotes of the week - all about documentation
_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
Quotes of the week - all about documentation
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
Quotes of the week - all about documentation
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
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.
Quotes of the week - all about documentation
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
Quotes of the week - all about documentation
It keeps amazing me that intelligent, cooperating people can't see the value of documenting what needs to be documented.
Quotes of the week - all about documentation
Quotes of the week - all about documentation
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.