I recently discovered a new technique for reviewing my own code. Previously, I had the experience of flowcharting algorithms for two different patent applications. While producing the diagrams, the process of converting the code to a different form caused me to find bugs in both cases. The problem with flowcharts, though, is the constant fiddling with the graphical representation and adjusting things to fit in the space or how best to split the diagram when it does not fit in a viewable area. Because it had been so successful in forcing me to review my code at a more thorough level, I have been on the look out for something similar that would allow me put the code through an essentially isomorphic transformation without the complexity and overhead of a graphical layout to get the same benefit.

I came across a paper by Maarten H. van Emden that uses a matrix to describe the state transitions that take place in the code where the matrix represents a dual-state machine, where both the control flow and the data state are represented. I modified his method somewhat to adapt for use in a spreadsheet. He added the states starting from upper right going down and to the left. For a spreadsheet, it works much better to go from upper left going down and to the right. Maarten showed in his paper how to generate working C or Java code from the matrix, but I went the other way by converting existing C code to a matrix. The effort to convert my code to another form forced me to think through the code to a degree where I found numerous errors in the code I had previously missed. These included errors that passed the unit tests, working correctly in a single thread, but entirely wrong from a concurrency standpoint.

The other advantage was that it also allowed me to review the code in terms of its complexity, namely the number of states and state transitions involved. I found that I needed to reduce the number of states (to a reasonable number that would fit on a single spreadsheet tab) required refactoring the functions, thus improving the level of abstraction and greatly simplifying the code. The results can be seen in my current github repository, and the spreadsheets, which are in Google Sheets, can be seen in sheet1, sheet2, and sheet3.

I must say that this technique has helped me produce some of the best code I have ever written, both aesthetically and correctly, in which I justifiably can have a lot of confidence.