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?

Xojo 2017 R3

Xojo 2017 Release 3 is now available.  As with all Xojo releases there is a mix of new features, big and little changes, and a host of bug fixes.  I’ll highlight some of the big items.  See the release notes for the complete list.

Perhaps the biggest change in Release 3 is that this is the first release where the IDE itself is 64-bit.  For macOS this is the only option.  In Windows the installer will choose the proper version for you system.  For Linux, the IDE is only 64-bit and will not run on 32-bit systems (note that it can still created 32-bit executables).

This is a major milestone for the Xojo IDE and is the culmination of many years of hard work by the developers.  It’s hard to imagine the work involved in taking a large product, like the Xojo IDE, that once assumed everything was going to be 32-bit only and rewrite practically every class, method, and function to ensure it works properly in 32-bit and 64-bit on Mac, Windows, and Linux.

So what is the deal with 64-bit? It lets the IDE use a lot more RAM.  In Windows especially this has been a limitation.  Some processes in the IDE, and in our built applications might be faster (emphasis on the might).  And since most computers are shipping as 64-bit these days it seems archaic to keep using 32-bit applications and in some cases for Linux it’s really hard to run 32-bit apps on a 64-bit machine.

One thing that changed because of the move to 64-bit is that the IDE Auto Saves the project before a debug run in a different way from previous versions.  Prior to R3 it used memory blocks to save this data in temporary files in case the IDE crashed.  In R3 it still saves but it’s using a much slower method.  It’s a long and drawn out explanation but it’s because of memory fragmentation that can happen even in 64-bit builds.  On very large projects this can take a LONG time and can make the IDE look like its stuck since there is no visual feedback of what it’s doing.

If this is a problem for you there is a way to get the IDE to NOT AutoSave the project before the Debug Run.  Warning:  This is for advanced users that understand the implications of doing this:

Confirm that Xojo is closed. You can set ‘Autosave Allowed’ to false the following ways:

macOS:

Edit the Xojo Preferences ( ~/Library/Preferences/com.xojo.xojo)

Add a key with either a true or false value

<key>Autosave Allowed</key>

<false/>

Linux:

Use the same key entry style as macOS inserted in ~/.Xojo.Xojo

Windows:

Use regedit to edit HKEY_CURRENT_USER\Software\Xojo\Xojo

Add a new DWORD value with the name “Autosave Allowed”

a value of 0 is false

a value of 1 is true

Another issue for 64-bit builds is the Currency data type.  According to long time Xojo developer Kem Tekinay using Currency is not recommended in 64-bit builds due to comparison issues.

The IDE now cleans up properly after a debug run.  This should eliminate the issue with the IDE showing a file IO error when trying to do multiple debug runs.

Layout Editor

Dragging IDE windows around with thousands of controls on the layout renders better now.  It is still recommended that you use container controls to limit the number of controls on each window.

Report Editor

Fonts on reports, especially in 64-bit builds, are now rendering at the proper size.  The Report Editor now honors locks as it should.

Code Editor

The Code Editor now highlights the lines of code blocks.  I’ll be honest, this is a totally unnecessary bit of fluff in the code editor but after using it for a few weeks I find that I like it.

The Automatic Code Reformatting now takes effect when you click away from the line of code.

Remote Debugger

The Remote Debugger Stub was rebuilt using 2017 R2.1 and thus has a speed boost.

The Mac Remote Debugger is now 64-bit and can run 32-bit applications as well.

64-bit and ARM Console debugger stub’s are included.

Lingua

Lingua now has a scripting folder where you can run XojoScript to manipulate the translated text.  This is really useful in post-processing where if your translator puts quotes around everything, or likes to put the source and translated text together.  Presumably an enterprising developer could use XojoScript to connect to a translation service.

ARM

XojoScript now works on Linux ARM builds.

Windows

64-bit Widows apps now display manifest settings in the advanced tab of Windows build settings.  This allows you to set Windows versions and privileges for your app.

iOS

Support for iOS 8 and iOS 9 has been dropped.

Xcode 9 is now supported as well as 64-bit debugging.

Web

Internet Explorer 10 support has been deprecated.

A number of bugs in the Web framework have been fixed.

Conclusions and Opinions

All-in-all, this release is an important one since the road to 64-bit has been a long and arduous process.  Xojo Inc. has missed on a number of promised deadlines this year and while some of them were under their control – many were not.  Let’s hope that 2018 is much kinder to their schedule.

I would expect the slow Auto-Save that popped up with the 64-bit IDE to be addressed at some point.  One personal opinion on this that irks me is their temporary fix for ‘advanced’ users.  Come on.  Really?  Stop treating us like children.  I don’t know about you, but in my 16 years of using Xojo I’ve only tried to use the AutoSave feature a handful of times and I can only think of one case where it actually saved me any time.  Keep in mind that you might very well never experience the issue if your project is small but I tend to have big projects and it’s a noticeable lag.

I did not like code block highlighting in its debut.  I felt that it was a complete waste of programming time.  After using for a few weeks it’s not that bad but I’m not sure it’s all that useful either.  I suppose if you have have six or seven layers if nested code it can be helpful but I tend NOT to do that.  It also might be really helpful with really long methods, and again, I tend not to do more than a page of code (I hate scrolling).

As with all Xojo releases it’s important to test your projects to ensure everything works as you expect.  I would expect a few things to shake out of the 64-bit IDE as more developers bang on it.  Xojo is a big project and the beta testers (myself included) can’t hit every single feature.  I’m not sure if I’d expect a dot release from R3 but I also wouldn’t bet against it.

Give me your thoughts!  Do you like R3?  Is it stable and reliable?