Rants, rambles, news and notes from another geek

Source Code Is Meant to Be Read by Humans

Gordon Weakliem writes:

Today I read a paraphrase of the Perl design principle that went “programs are meant to be easy for humans to write, and only incidentally for people to read”. Contrast that with Donald Knuth’s statement that “Programs are meant to be read by humans and only incidentally for computers to execute”. While those statements aren’t necessarily mutually exclusive, I think that where you stand on those questions says a lot about how you write code and what kind of language you prefer.

I’ve certainly read some Perl programs that couldn’t have been easy to write! :) Seriously, though, Gordon has hit the nail on the head here. I am a strong believer that code is documentation. In fact it is the most accurate documentation you have about a software project. It must be easy to read for the humans who will have to read it 3, 6, 12, or 36 months from now. The UML diagrams will probably be lost. The requirements spec will be so out of date that it will look like a completely different project. But the code is the best document there is to tell you how the code is put together and what it does.