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