Structuring Success

Dear KV,

In teaching an algorithms course this semester, I discovered my students had received very little instruction about how to divide their code into functions. So, I spent a weekend trolling various programming handbooks and discovered most of them are silent on this topic. I ended up writing a handbook (see https://bit.ly/4cc3TdL) to help my students, but was struck more by the advice gap. We just do not give people guidance!

Guiding Light

Dear Guiding,

Well, luckily, you are in the guidance business! I read over the handbook, and not only do I agree with it, but I think I have given similar advice—although not so nicely—in these columns in the past. I also note that you cite one of my favorite books on the topic of good software engineering, The Practice of Programming by Kernighan and Pike (see https://bit.ly/3VjUCtl), a classic I read when it came out more than 20 years ago.

I want to look at this problem from another angle, since you have so nicely and concisely gone after the prescriptive advice. I have not taken your class, nor even sought out the syllabus, but as you say that it is an algorithms class, I wonder if that is a part of the challenge. I find that people develop a taste for good program structure—which is what you are arguing for—only after they have either been exposed to it in a well-written system or had the need thrust upon them by the problem they are trying to solve. If the programming guides you consulted are like the ones I have seen, they definitely have that 1980s PROGRAMMING IN BASIC mode of thought, in which the goal was not to understand the program so much as it was to type it into your personal computer correctly so you could play the game they were showing you.

In the modern world, this type of programming has been carried over to the Maker-like tutorials, those that blink a light or make an art project out of an Arduino and some string. It is not that these projects are bad (although the ones with sound are ultimately annoying when you are sharing a makerspace), it is that they are not meant to teach good software engineering. And the problem is not limited to the hobbyist world. While many algorithms can be broken down into constituent parts, textbooks do not often treat them that way, preferring, instead, to get the whole concept across in a large block of pseudocode. Good software structure is difficult to show in a linear form such as a book chapter; it is best when directly experienced.

To that end, I strongly suggest your first project be one that requires some level of software structure, and this can be done in a few ways. The cruelest, surely, is to give the students such a horrendously complex assignment that the only way to solve it is through proper structure, rather than through the cleverness of the algorithmic design of a single function. The algorithm itself can be trivial, but the requirements for acquiring, processing, and storing the data, along with some nasty reporting requirements, would definitely make your students more aware of why they might want to structure their code. Interacting with the underlying system to get input, store output, and make reports is a straightforward way of ensuring the students want to have structure.

Another possibility, and one that might be a bit less cruel, is to cite the algorithm within some other system that already has structure. Rather than write a sorting algorithm that just takes an input string and produces the sorted string (as we did when I was an undergrad), have the students replace an algorithm in an existing system—for example, one that deals with encryption—where there can be choices of algorithms but the framework is not under their control. The modern world of open source software should help you here. You can use many different pieces of software, admittedly of highly variable quality, as the frameworks for such homework.

The problem with software structure is people do not really learn it until they really need it, and your homework assignments will have to force them to look closely at how they are solving problems, not only through algorithms but through structure.

Code Hoarding
https://queue.acm.org/detail.cfm?id=2897034

Koding Academies
https://queue.acm.org/detail.cfm?id=3361872

Undergraduate Software Engineering
Michael J. Lutz, J. Fernando Naveda, and James R. Vallino
https://queue.acm.org/detail.cfm?id=2653382