When you’re writing code we all know it’s a great idea to use method, property, class, and variable names that make sense. It also makes sense to add in comments on code that isn’t clear. But do you code in such a way that your future self won’t invent a time machine and come back and slap you in the face? This is how you should be coding. You really want your future self to appreciate the work your current self is doing.
One of the current projects I’m working on interfaces with multiple devices via serial communications. Each one of them uses a different protocol (naturally) and some of the code was written by me and some of it by others. Before I get into the Other Peoples Code (OPC) portion I’ll talk about my experiences with coming in cold to something called ccTalk. ccTalk is a low speed communications protocol for use with Coin and Bill Accepters.
Had I ever heard of ccTalk? Nope. So the first thing I did was Google it. I found a few helpful blog posts on it (saved the links) and found a few projects in Java and in C# and downloaded what I could. I studied their code. I found specification documents for ccTalk and device documentation and all were immediately added to the source code repository. Why? Because as soon as I move on to the next project I’ll forget the details. If the information isn’t relevant in two weeks I’ll most likely forget about it.
In writing this post, I came to the conclusion that I also need to add any required drivers to the repository as well. From experience I’ll inevitably need them in the field and if I don’t have them on hand I’ll waste time searching for them again. Were they sent in an email, on the packing CD, or available from the website? If it’s in the repository I won’t have to worry about it!
In my source code I document the message numbers I’m sending to the device and putting relevant details on the response and what I’m expecting back. For ccTalk this might be a simple acknowledgement/busy response and depending on the command some additional data. How much data am I expecting? Did I get less? Did I get more? Does the checksum match my own calculation? Do I have a way to create a log of the communication stream and is that log in human readable form or in hex?
This might seem like overkill but I’ve had to go back to my own code years later and relearn what I did. This has involved finding the manuals again and trust me that’s no fun. I think it best to assume you will not be the programmer on this project in the future. Perhaps you get hit by a bus tomorrow and your client has to find a new developer.
The OPC portion of this project is using a different serial port to a different device and has exactly 24 comments in it. Most of the comments don’t help me. Commenting ‘If Serial1.open then’ doesn’t help me. There are a few ‘Return //Exit this Routine’ comments that again would be more helpful if I knew why I have to exit the routine because it’s not immediately obvious from the rest of the code. There are no comments regarding expected data. No defensive coding techniques to ensure that if something is missing or garbled it can handle it gracefully instead of just crashing. Of course there was no documentation for the hardware either so I’m not even entire sure I have the darn thing hooked up properly – all I can do is assume that I did until I get that documentation. All-in-all I want to jump through the screen and scream at the other developer to a) put in useful comments; b) include the documentation with the source code; and c) include drivers and utilities that a newbie would need!
I try to make sure, in my code, that the developer that looks at my code in six months doesn’t curse me. I say enough bad things about myself as it is.
What sorts of things do you do to ensure future you doesn’t curse your current self?