Why comments are important.

When I teach programming, apart from pushing code readability, I try to emphasize the importance of writing decent program comments. All too often I hear students proclaim that the “code is self-documenting“. Really? The only true self-documenting code is written in Cobol, and that’s partly because of its English-like syntax, and the inability to really write obfuscated code (unless one considers the entire language to be obfuscated – and some do). It doesn’t take a lot of effort to add some comments. Not the trivial “This statement adds one to the variable index” – that *should* be common sense. What needs to be there is the stuff that when you look at it in six months time, you’ll actually know what the code does. You write a nice algorithm, code it, it works beautifully – then you abandon it only to come back months later, look at the code and wonder how it actually works. We are *all* guilty of it. And we should know better.

A program should contain the appropriate amount of instructions for humans, next to the actual code doing to the work – so that humans can understand it. The program itself doesn’t care, it strips out comments, and all the pretty whitespace we add for readability. But humans care – or at least we should care more. The purpose of a comment should be to not only explain weird and cryptic code, but also ensure that the reader always knows exactly what is happening. The worst offenders? People who write obscure, compact, unintelligible code, provide no comments, and post the code for others to use.

Programs must be written for people to read, and only incidentally for machines to execute.
― Halold Abelson & Julie Sussman, Structure and Interpretation of Computer Programs

Billy bookcase + books = sag

I started writing this blog as a place to post stuff on programming. It’s not meant to be a vast repository of knowledge, or anything like that. I don’t write apps, nor do I design large pieces of software. I write programs to solve problems – in C, Fortran, Ada, Cobol, or Python. I don’t use fancy tools, I generally use the command line and edit in vi, or TextWrangler on the mac. I write programs on OSX or Linux, no Windows.

What is interesting to me is how so many of the programs we use are intrinsically simple. It is of course turning them into apps, adding usability, and graphics that makes the code base more complex. The algorithms themselves are simple. Take for example the simple task of building shelves. One of the biggest problems with shelves is that they can sag with the weight of books. A perfect example of this is the Billy bookcase from Ikea. Made of particleboard, it will sag when significant weight is put on it – e.g. hard cover books. Use the sagulator to calculate the sag of a  30″ Billy bookcase that has a depth of 10″ and a thickness of 3/4″, with a load of 20 lbs/ft will result in 0.2″ total sag, which is excessive. So a simple deflection calculator is of great importance when designing a shelf and selecting the appropriate type of wood.

Why does shelf sag matter? Because it is a calculation which can be easily turned into a program, and would make a good candidate for an app. From a pedagogical point of view it provides a nice progressive pracnique – it can be introduced as a simple program in introductory programming (with all information provided by the user), extended to allow the user to select a wood species as opposed to inputting the “modulus of elasticity” (think data structures of some sort, maybe store the wood information in a data file), used to design an app for a mobile device, and again in a course on usability. A similarly interesting app is one that calculates the size of furnace needed for a house. Utilitarian – yes. But let’s face it, *most* programs have to perform a useful function. Not every program can be a game app that rakes in millions in revenue.

Anyways, back to Billy bookcases for a minute. If you’re like me, then there isn’t just one row of books on the Billy bookcase – and they certainly aren’t all paperbacks. So here are some stats. I measured the weight and dimensions of a hardcover and a paperback book, and converted the results to ounces per in^3:

Paperback = 0.268 ounces per in^3
Hardcover =  0.428 ounces per in^3

Now calculate the volume of a standard Billy shelf on a 30″ bookcase = 30″x10″x10″ = 3,000 in^3. So it the shelf space is crammed with paperbacks, or hardcovers, this is what the shelf load would be:

Paperback = 804 ounces or 50.25 lbs
Hardcover = 1,284 ounces or 80.25 lbs

Sag would be 0.2″ for the paperbacks, and 0.32″ for the hardcovers. Which likely seems about right if you have these book cases and cram them full.