Coding Habits To Keep You Alive When Time Travel Is Invented

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?

To Be or NOT To Be

I’m probably getting into quasi-religious questions here, but I’ve been reading someone elses code in an OPC (Other Peoples Code) project and they use a lot of statements like this:

If Not aBooleanValue then
   
   //do something here

I find this harder to read and much prefer:

If aBooleanValue = false then
   
   //do something here

I understand why people want to use the former but to me it reads backwards.  I have to flip the value in my mind before the variable and then keep that in mind for the eventual comparison later.

And don’t get me going on people that do things like this:

If Not (SomeFunction > 0) then

//do something here

To me, that’s just being too lazy to correct your code.  What should be explicitly clear is now not so clear (granted, this is a super easy example but you get my point).  I like to code for explicitness which means it’s easier to read (by me or someone else) weeks, months, or years from now.

I’m lazy.  I freely admit this.  I prefer to see the test values explicitly called out.  So something like this:

If aBooleanOne = True and aBooleanTwo = False and aBooleanThree = True then
   
   //do something here

is better than:

If aBooleanOne and Not aBooleanTwo and aBooleanThree then
   
   //do something here

For every ‘rule’ of course there’s an exception.  For simple boolean comparisons where I am checking for true I tend to write:

if aBooleanValue then
   
   //do something here

The True check is explicit and there’s only one variable to compare.  As soon as I use a second variable I will change it to be more explicit.

It’s such a little thing but when reading code one seems much easier than the other.  Or perhaps it’s just my OCD shining through.

What do you think?  Am I being overly critical or do you have similar beliefs?