You’re not shipping your computer

Not all computers are the same. Here, you are entitled to go Duuuh!, but bear with me. What works on some computers, does not always work on the others. Why does it happen ? And more importantly, what can you do to protect yourself ?

Over the years I spent a lot of time on it works on my machine type of problems and this is a list of common issues I encountered.

Table of Contents

Timezones

If the app you are building cares about time in any way – updated time, created time, time until a particular event – it’s easy to forget there are multiple timezones out there. The issues I saw fall into a couple of categories:

You (the developer) are on a different timezone than the user. This can really confuse reports that you are getting (e.g. this happened around 10am) and can have a big impact on your release schedule (e.g. it’s late afternoon for you – a quiet time, but for your customers is the busiest time of the day).
Your users are on a different timezone than the server. This makes the error logs out of sync. 10 am for the user is not necessarily 10 am for the server. Also, this is a problem if you want to expose the server time (e.g. to display a live clock).
Different parts of your system are in different timezones. VMs running microservices make it easy to have your system spread out across the globe. This means that your database and your API server could be in different timezones. Unless you fix this explicitly, you will end up with miss-aligned logs or entries in the database to be added with the wrong timestamp.

Charsets

I have been hit by LF vs CRLF issues more times than I want to admit. Particularly when I was working on a Windows machine and shipping code to some UNIX server. The code sometimes broke without any apparent reason.

More than the code, I find config files to be particularly vulnerable. The story usually goes like this: I open a config file in something, silently, changes the line endings from LF to CRLF. I make a deployment and suddenly some service fails to start on the server. Just make sure to check the line ending if something, mysteriously, fails to start.

Date locales

For software developers, the question Which is first? The day or the month? is often times a confusing one. The reason for the confusion is because the correct answer is It depends on where you are. The same string can mean a different thing: 10-03-2021 ca be either 10th of March or 3rd of October. And the worst part is that this is a client side setting that you, as a developer, do not control.

The solution to this is to always force a date format on the user, and don’t just settle for the default one the browser / system comes with. Alternatively, you could switch everything to unix timestamp, but that is not always feasible.

Different browsers

The HTML and CSS standards have evolved a lot over the years. Even so, from time to time browsers misbehave and break compatibility. Alternatively, in an attempt to move the tech forward, some browsers might introduce features that are not yet part of the standard, so not supported by other browsers. The takeaway from this is to always test your app with multiple browsers. Browserstack offers a great solution if you need a particular version of browser. If you don’t have access to numerous browsers to test on, you can have a look at a browser compatibility checker before you implement a feature.

Environment variables

Environment variables are a set of key-value pairs that live within the OS but they can be accessed from code. More often than not, your code assumes that some environment variables will be present and have the right value assigned (some executable to be available on PATH, for example). You should ensure that when your code gets deployed, whatever environment variables you require are created. There is no generally accepted solution, but I find the solution that dotenv proposes is quite neat. If you’re not using JavaScript, you might want to look into a similar solution for your language of choice.

Different databases

If your project does anything meaningful, you probably have a database. You should have at least two environments – a test environment and a live environment. If you don’t and are currently testing in the live environment, bookmark this page, add a test environment and come back to this article later. This setup opens the door to a number of database-related issues:

The databases have a different schema (tables/columns missing from either the test or the live environment) – The environments can be kept in sync using a database version control system.
The data is not up-to-date (some data that your code needs has not been added yet) – Make sure that, if there is any data that your code relies upon, the data is in the database you are using.
There is not enough data (the volume of test data is nowhere near the size you have in the live environment, so there is no way you can test your code at scale)- This one is a bit tricky. Sometimes, your code requires lots of data to allow for a complete test. You can create mock data generators alongside your code and use those to populate your database with enough seed data.

Different screen sizes

Even though this is mostly relevant for mobile apps or mobile-focused websites, it’s worth to keep in mind that there is a huge range of possible screen sizes. And sometimes, it only looks good on your screen. Change the aspect ratio of the screen a bit and everything looks broken. The best mitigation I could find for this is to make sure you test your app on a wide range of screen sizes. Chrome developer tools can be a good place to start, and you can move onto browserstack if you need a fuller experience. Add a step in your release process that says every release should be tested on at least a manageable number of screen sizes. If you can automate the process, even better.

Users are unexpected

If there is any way in which your app can be broken, it’s only a matter of time until someone will stumble upon that use case. And when that happens, you need to be ready. You should be in a position to collect enough data to allow you to reproduce the error case on your local or test environment. Even more so, you should ensure your users have the right tools to report issues to you quickly and correctly. Help them however you can: show a meaningful error message on the screen (ideally you would have a different error message for every error condition in your code), display contact details for your support team (or even a general contact email can help), autofill bug report forms with stack traces and error codes and submit them alongside the user report.

Conclusion

Writing code is hard, writing code that works everywhere is even harder. Different environments are now just part of the game. The best thing you can do is to be aware of the differences between your computer and the user’s computer, and take action to ensure that these differences don’t cause problems. Hopefully, this article provided some pointers. And when issues do appear, make sure you already put in place the right tools to extract meaningful data from the error and be able to diagnose and address the issue quickly.