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

Quotes of the week - all about documentation

Posted Dec 18, 2008 12:33 UTC (Thu) by spiv (subscriber, #9031)
In reply to: Quotes of the week - all about documentation by giraffedata
Parent article: 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.

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

(Log in to post comments)

Quotes of the week - all about documentation

Posted Dec 19, 2008 2:51 UTC (Fri) by giraffedata (subscriber, #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).