Maybe. . .
I remember reading a T-shirt or poster or something somewhere a while ago that said:
“REAL programmers document their code.”
I’ve had enough experiences of coming back to code weeks, months, or even years later and having no effing clue what I was doing.
My first experience of this was writing a hardware test program that would run on an 8085 in a piece of “office-terminal” hardware our company had developed that had been repurposed as a test fixture. It was written in 100% Intel 8080 assembler using a text editor and the “asm” program on a Kaypro-I “portable”, (as in a suitcase), running CP/M. I wrote a first pass at it, and though it worked, it still had a lot of issues. I sent it out to the production floor as an (ahem!) “early beta” just to see how it would be received.
Several months later, someone up there in the rarefied atmosphere of upper management decided that my “hobby project” that I had done during downtime between aircraft contracts had merit, had an actual project accounting code issued that I could log time against, and had me pulled off my current task and told to work on that exclusively.
When I returned to that code - I was absolutely stonkered!
- What the [censored] was I doing?!!
- What the heck is THIS?
-
This is odd, why did I do this thing this way?
I had no 'naffing clue what I had done or why I did it the way I did. It was as if a total stranger had written it.
It took me a couple of weeks munging the code to finally figure out what I was doing and regain my thought processes - at least in part.
As a result of that, I stopped working on the code itself and began working on documentation:
Documents that captured my thought processes, documenting the code itself, rough flow-charts, etc.
The “Big Boss” who authorized my project stopped by one day to see how, (and what), I was doing. I explained to him that I had stopped actual coding in favor of documenting what I was doing, what I expected to accomplish, and how I planned to do it - aided by me commenting the source-code with my thoughts as I went.
I explained that the “first cut” of the software was hacked out as an experiment and, as a result, it was poorly documented - and as a consequence I wasted several weeks figuring out what I had done. I told him that I had “had enough” and decided that if this was going to be a Real Project, it needed proper and complete documentation.
He sat down next to me, read through all my documents that I had generated up to that time, saw my commented code and, after a pregnant pause that had me holding my breath, he gave me a huge grin, nodded his head, slapped me on the back, and told me I was the second individual he’d ever met that realized the importance of clear documentation.
Though I was working independently, I still “reported” to my old supervisor on the line. About a half hour after the Big Boss left, he comes running in, in a state of wonder and amazement and told me that this Big Boss Himself had awarded me a several-dollar-an-hour raise on the spot along with a step up in pay-grade, (in addition to bonus-raise itself. In essence I received a double-raise), all retroactive to when I started the project. (No, I wasn’t an “Engineering” type, I was a lowly hourly technical employee.) After that, all the nay-sayers simply vanished into the woodwork.
The result is that I not only copiously document my code, but, (if the code is complex enough, like this joystick-controlled robot project), I write theory and expectations documentation that captures my thought processes while coding. I also like to create a broad overview document that might be called a “project plan” or “project roadmap” that describes what I want to do and how I want to accomplish it. As I progress through the project, the “planning” document gets updated.
Major sub-assemblies get their own plan.
I do not implement this as fully as I would like to, but I’m working on it. My earlier “craps simulator” game project, (the second program I ever wrote in Python), had it’s own flow-charts and state-diagrams that described every module in the program, how they related to each other via program flow, what they expected as inputs and what they provided as outputs. It kept me from loosing my place while writing.
) it would be a tabulated list showing the API feature, how to use it, and perhaps an applicability grid - i.e. which Dexter device(s) it works on.
), we can author articles and take some of the load off of their shoulders.