Quotes of the week - all about documentation

Posted Dec 12, 2008 19:35 UTC (Fri) by giraffedata (guest, #1954)
In reply to: Quotes of the week - all about documentation by hppnq
Parent article: 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.

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).