Last month, by way of involvement with the Union of Concerned Scientists, I put all of my technology projects on hold and dedicated my energies to our US elections. Starting those projects back up again was surprisingly challenging.
Working on the elections was a great experience, and I heartily recommend it to everyone. As engineers, we don't often take the time to look at the world through a political prism and join the “grass roots” levels of civic life.
Last week though, with the elections and celebrations over, and the last of the paperwork completed, I got back to my workbench. I started to pick up my MCU projects where I had left them -- which, as it turns out, was easier said than done.
The problem is pretty fundamental. You can forget a heck of a lot in a month -- and although I do try, my efforts to document my projects as I go along seem to always fall short.
I left two hardware projects in a “working prototype” state on my bench. I remember that they were working (more or less!) –- but it seems that the schematics I drew up didn't quite match my physical hardware. I'm sure they did match at one time, but I like to refine my designs as I go along -– and my diagrams tend to lag the changes I make by a few days.
That's no problem if a project gets set aside briefly, but setting one aside for a month is a whole different story. I've ended up spending a lot of time “reverse engineering” my own design efforts just to get to the point of having reliable, complete schematics to work with.
And that's just electrical. Keeping up with mechanical layout is important, too. One of the schematics I left shows four IDC connectors on my breadboard: J1, J2, J3, and J4. Those connectors are indeed on my physical board -– but before I took that month away, I neglected to make at least a sketch of which connector is which on my actual board. Which one is J1? And which pin is supposed to be pin 1 on J1, anyway?
True, this can be sorted out with an ohm meter without too much effort -– but if I had taken a little more time with my project documentation as I went, that wouldn't be necessary.
And then, of course, there's the issue of software documentation.
I left four software projects in-process, and each of them involves an MCU program (assembly language), and a companion PC program (written in object pascal). All of the documentation I left for these programs was contained in a few text files (notes I'd written on the fly as I wrote my code), and there were, of course, comments here and there embedded in my code itself.
As it turns out, that's nowhere near adequate.
Many of the variable names that seemed perfectly reasonable and clear when I assigned them looked, much later, totally meaningless. “Restore” is a perfectly good word and a nice, short name for something, but after one month I had no idea what. Further, some of the “tricks” I'd used in my assembly code to handle instruction parsing (to cite one example) were so tricky it took me an hour to trace them back through all of their context and decipher how they actually worked.
To compound the difficulties, it seems that all of my programs had a few bugs in place when I put them on hold, and my “to do” lists of those bugs had never actually been written down anywhere. There weren't that many bugs, after all, and remembering them between debug sessions was no problem... The consequence of that oversight was that I had to invest a lot of effort re-discovering and re-debugging old code –- a real time-waster.
Slowly but surely, I am getting back up to speed –- but I have a way to go yet. Meanwhile, this is offered as more of a cautionary tale. What state would your projects be in if you suddenly had to set them aside for a few weeks? Do you have any techniques you use to minimize the sorts of problems I've described here?
Tweet This
