Another Giant Refactoring Milestone

Yes, I’ve once again rearranged (and in some cases, rewritten) the entire Keyglove codebase. It was totally worth it, for reasons I will outline in a moment. Before I do, I want to get to some housekeeping stuff.

This is the first of a few could-have-been-backdated posts which chronicle the developments in the Keyglove project’s recent past, but which I didn’t write about at the time they occurred (oops). This miniseries of historical non-fiction covers the past 13 months or so, starting around the beginning of November 2014. “Over a year, again?!” I hear you cry. Indeed, and I apologize for another long period of silence—even though it fortunately wasn’t totally devoid of progress. For an extremely brief explanation, here’s a list of the “life stuff” that has happened during the same period of time:

• Bought a house
• Had a child (which is to say, my wife did)
• Moved into the aforementioned house
• Employer got bought out by Silicon Labs
• Unexpected family medical issues
• Took a new job opportunity at Cypress

I had no desire or intention of staying so silent, but…well, I’ll just say that it’s been quite a year.

Okay, back to the stuff you came here to read.

My adventure with this huge refactoring endeavor started with a bug that I couldn’t figure out. It made zero sense, and the behavior changed without any detectable reason based on seemingly unrelated code changes. My announcement to the world of this fact came in the form of this tweet:

Running into a strange bug that I think must be a memory leak. I found a workaround, but the behavior in both cases makes no sense. Argh…

— Keyglove (@keyglove) November 2, 2014

After continued troubleshooting yielded no progress, I eventually posted my predicament to the Arduino Forum.

I am running into a problem which seems to have to do with the code execution pointer, and the behavior makes zero sense at all. There is a conditional statement which doesn’t match, and since the code it controls is only one line, I omitted the surrounding { } braces for brevity. This is a pattern that I have reused many other times all throughout this fairly complex project without any observable bad consequences. However, when I let the code run this way, execution apparently stops at that line…

Three pages of sometimes maddening miscommunication or misinterpretation later, I got a startling revelation when the patient and wise Nick Gammon pointed me towards a pre-written resource he put together quite some time ago on Arduino project structuring.

This was a big surprise to me, because the last I’d heard, Arduino’s IDE imposed some pretty weird restrictions on code structure (one of its presumed weaknesses), including that you could only have typical .cpp/.h source/header file pairings in included libraries, from the official “Libraries” folder. This meant that the main project had to be one .ino file and a big collection of header files, each of which actually had a both declaration and implementation code inside (typically a bad idea). Nick’s guide proved that this was an incorrect assumption on my part.

I've just (!?) learned that Arduino sketches can be structured the same way most C++ projects are, with .cpp/.h pairs within the sketch.

— Keyglove (@keyglove) November 5, 2014

This makes me more giddy than it probably should, despite (or because of?) the massive code restructuring that is about to take place.

— Keyglove (@keyglove) November 5, 2014

After no small amount of work completely restructuring the whole Arduino project, I had all of the code back in line with conventional organization, and the inexplicable bug disappeared. Nick Gammon is my hero.

I pushed the massive commit to the Github repo as soon as I got it to compile and function as well as it had before the refactoring started—except for the fixed bug, of course. In addition to that fix, the new standardized code structure allows me to avoid some really strange “workaround gymnastics” that I had to include before. The order of #include lines in various places had been extremely delicate, with way too many compile-time dependencies built into the order of those lines. The new code is much safer, more obvious, and more forgiving. Three cheers for collaboration!