Code Listings - the Path to Illiteracy? -

Code Listings — the Path to Illiteracy?

Tom DeMarco, noted software guru and wag, complains “programmers don't read.” In an attempt to get some quantitative data we conducted a poll on the topic a few months ago. According to that poll, 48% of respondents read more than four books in the last six months, a pretty impressive number.

Yet another 21% read one book or less. Perhaps this is due to the curse of TV or overstuffed lives. But surely this figure bodes ill for the future of software. This is a dynamic, evolving field; there's a constant flow of new ideas, many of which are applicable to any embedded person. Unless we keep up with these new developments, primarily by reading books, our careers will stagnate and wither.

A publisher of technical tomes recently told me he wonders if DeMarco was wrong. Instead of engineers not reading, he wondered if they can't read. We were discussing a book that was nothing more than long listings of Java with scanty English explaining the software. Sometimes it seems that modern technical books are either in the “Idiot's Guide” camp or are a dreary thousand pages of source code, with a CD-ROM sandwiched in the back cover.

He then told me that one of the best-selling Unix books is nothing more than script listings, with virtually no prose. If that's what makes a best seller, then I cry for the future of technical writing.

Of course it is important to read code. But most of what's published in these sorts of books is awful. It's poorly documented and badly structured. Perhaps the little bit of text that accompanies the listings is there because the commenting and design is so awful. Why not write it correctly, stuff the Java on the CD, and then use the wonderful media of the printed page to convey something important?

If you like code books, check out Jean LaBrosse's two books (MicroC/OS-II and Embedded Systems Building Blocks). Both contain source listings so beautifully structured they get as close to poetry as software can be. Read these to learn how one can and should create firmware. But they are rare exceptions in what passes for computer literature.

Sometimes a long listing accompanied by an insightful explanation can teach a lot about a specific subject. More often, though, I'd suggest the readers are better served a high-level flow chart or PDL. It's a much more efficient way to get the ideas across. Implementation details, if needed at all, should live on the web or the CD.

I'm just finishing Petroski's The Pencil, 350 wordy pages about the engineering and history of this simple writing instrument. One friend who was hefting yet another book filled with listings looked at The Pencil aghast, unable to imagine how anyone could read — let alone write — so much about such a little thing. He was quite happy to turn back to his code book. So maybe I'm wrong. What do you think?

Jack G. Ganssle is a lecturer and consultant on embedded development issues. He conducts seminars on embedded systems and helps companies with their embedded challenges. He founded two companies specializing in embedded systems. Contact him at . His website is .

Reader Feedback:

Personally, I think that ifa programmer likes to read”code”, then that individualis a happy camper. Thinkabout it… would you say itwas wrong for a hardwaredesigner to look at otherdesigns (schematics), or fora builder to examine otherarchitectural drawings?While it may be nice for anEE to know the history behindthe transistor, and the manystories about the first computer (through reading), that EE will learn the tradeby looking over the shoulderof collegues and observing other designs.I absolutely agree that(especially in this industry)we must constantly be broadeningour horizons; however, justas a builder ultimately looks at various blueprints to improve his/herown design plan, a programmer canonly benefit from reading throughwell written code.

Ed Sutter


When was the last time you read a coherent report from an engineer? You know, something that was more than a sentence or two?

Don't get me wrong, I am not talking about people who might have language limitations because English is a second language – I am talking about engineers who spent their whole lives in schools where Engish was the primary language.

While we need to have technical expertise, a lot of our job is communicating with other people – whether it be engineers, marketing, customers, sales, production, etc.

Schools need to spend more time, and businesses should put more emphasis on langauge skills – spelling (and grammar) should count.

Tom Mazowiesky

Firstly, I compose these comments as a private person. I believe a person should excel at hisher chosen profession as priority. Previously, as a supervisor of a university laboratory, I watched the emphasis being placed on writing good reports and also watched the capabilities of engineering students, as engineers, decrease with each subsequent year. Let programmers do what they do best, ie write code. They will not get paid if all they can do, is to write good commentry.

George Ramsay
R & D Manager

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.