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