Steve Tockey on Software Documentation and Comments

I’d like to share a hilarious passage by Steve Tockey from the very end of his excellent Software Design course:

I like to say, if you look at it seriously, today, we are actually in the stone edge of software. Literally, how we do software today is stone tablet and chisel and we are just chiseling the code.

What I’m trying to get across is the idea of literally a bronze age. We can do so much more by semantic modelling of the requirements. We can do so much more with literate programming. By keeping track of the intent at various levels. By explaining “why” (in documentation and comments).

If we did that more we would be into a new age of software where the cost of building a software, the cost of maintaining a software can be fractions of what we are spending today.

We just have to get over the hump of “Oh, but that’s not the way we always done it. We’ve always done it this old way.” But as John, one of my coworkers, says: “Is it working for us the way we are doing it?” With projects being late, with projects being over budget. With delivering defective software. I would say, it’s not working. We need to do so much better. And we can do better. We just have to wake up and smell the coffee.