Forem: Olavi Haapala

Learn from Your Mistakes

Olavi Haapala — Tue, 23 Mar 2021 18:59:00 +0000

In this blog post, I will be sharing what I have learned from creating and maintaining a Sailfish OS app for tracking working hours. It’s simply called Working Hours Tracker. I started the project in 2014 and have been developing and maintaining it ever since. The most recent version of the app was released on February 20, 2021.

When I started the project back in 2014, I had quite little real world experience from software projects. I had been studying for a few years at that time, but we all know that most of the learning happens at work or when doing some side projects. My limited experience and knowledge led to some of the interesting mistakes made during the project, and I’ll cover some of those and what I learned from those.

Background

You may not have heard about Sailfish OS, and that’s fine. It’s not very widely known. It’s a mobile operating system developed by a Finnish company called Jolla. They initially launched the OS together with their own devices, but later on they have been more focused on the development of the operating system and licensing it to different partners in addition to being close to bankruptcy twice.

Personally, I love the Sailfish OS, but there are still a few blockers for me to be running it on my main phone. The available hardware that is officially supported is not at a good enough level for my needs, especially when it comes to the camera.

Sailfish OS has still a small number of apps available in the store and a small number of community developers working on new apps. However, the small size of the community was one of the nice sides of my project. I think I was able to gain quite a lot of attention from the community because my app used to be the only time tracking application available in the Jolla Store. Check this tweet about how excited I was when the app reached 2k downloads in the Jolla Store:

Olavi Haapala 🇫🇮

@0lpeh

Working Hours Tracker getting closer to 2k downloads in Jolla store. Now at 1994 :)
#jolla #sailfishos

07:44 AM - 16 Apr 2016

In 2014, I was using a Jolla phone as my main driver and had the need for tracking my work hours in an easy way. I also wanted to try out developing mobile applications and this seemed like a great idea at that time. The simple features and UI is developed mostly for my initial needs, until I started receiving feature wishes and feedback from the users.

Getting Started

In order to get started with the development and building the initial version, I was looking at some of the example applications and code snippets and took heavy inspiration from a few Sailfish OS applications that were openly available in GitHub.

I built the whole application with a mindset of trying to build something without really knowing a lot about the platform or the best practices. I was happy when something seemed to work even though most of my solutions were not optimal. This was probably my first mistake, not figuring out how to properly design and implement a Sailfish OS application. But on the other hand, this was a great way to get something done and learn from your mistakes.

Lessons Learned

Here are a few selected lessons that I have learned while developing and maintaining this application for years. They are in no particular order and the list is not exhaustive.

Qt and QML

Sailfish OS is based on Qt and the views are written in QML. Since I’m a web developer, I ended up doing most of my UI and features in QML, which is the equivalent of doing everything with JavaScript instead of doing the heavy lifting on the server side. In the Sailfish OS case that would mean Qt (C++) level. Correctly using C++ code that use signals to keep the UI up-to-date and to receive events, was something I only learned quite late in the project, when I took a closer look at the documentation and some more advanced example applications.

The heavy use of QML for data processing and other stuff that should have been handled more effectively, lead in some cases to somewhat unresponsive UI. Mostly, it has been fine, but that might have been only because I haven’t been using the application with large amounts of data.

Additionally, I ended up writing some of the data processing and grouping in JavaScript instead of doing that on the database level with SQL. This happened mostly because it happened slowly over time when adding new features and additionally, I might not have been aware of the powers and features of SQL.

Backwards Compatibility

Backwards compatibility has been one the most annoying part of this project. I’ve had a goal to not break any of the earlier versions of the app, that someone might be upgrading from. This has led to some weird quirks and unnecessary migration checks that need to happen every time the application is started.

Sometimes, an update I worked on ended up breaking the application for many users and I had to do some more database migrations in order to fix the database for those users who now had invalid data in the database due to an invalid migration script.

In retrospective, I should probably not have cared so much about breaking the application for a few users at the cost of having to run unnecessary code for everyone every time the application is started. I think I could have earlier decided to release a v2 of the application that would not have been backwards compatible. Better database design from the start could have let to fewer migration needs.

Database Design

Good database design is important. This is probably one of the parts of the project that has made me want to forget about the backwards compatibility and start everything all over again and release it as v2.

The database design basically did not exist at all. No foreign keys are used. Linking between hour markings and projects are done by looking for the project ID that is saved as a string on the hours row. Same goes for tasks inside projects and so on.

And did I mention the format the 2014-version-me decided to save the hour markings in?

The hours markings are saved in the following format (simplified):

Date as TEXT
startTime as TEXT (HH:MM!)
endTime as TEXT (HH:MM!)
Duration as REAL
Breakduration as REAL

Why on earth did I want to save the startTime as a “HH:MM” string? You might realize what kind of issues this kind of crappy database design has led into. If I could go back in time I would change the database to at least save these as unix timestamps or datetimes.

This in addition to custom home made code for handling durations and displaying those as “HH:MM” is also why I ended up having bugs like this reported by a user, displaying the time displayed as “150:60”.

Testing

Automated testing of the application should have been thought of at an early stage of the project. Way too late in the project, after releasing a few extremely buggy versions to users, I tried adding some unit tests to the project, but failed to get them working and gave up. Right now there are no automated tests in this project.

Additionally, as part of testing a version before releasing it, a plan or a script for the manual testing would have been useful. I usually only tested on a few different devices and only tested those features that I remembered to test. Quite often some features that I didn’t think were affected by the changes I was working on, got broken by a bugfix targeted at another feature.

Debugging

Even if a good level of testing is done, your users will end up in some weird corner cases at some point of the time. You are lucky if you hear about these from some of the users. It means they care enough to contact you. One thing that was super useful in these scenarios was that I created a way for the users to easily send me the application logs as email to me.

Managing Releases and Release Notes

Managing release notes and releases in different platforms etc. takes surprisingly much effort. This is something you might want to consider automating as much as possible.

Current release instructions for this project consist of a list of 15 steps to go through when releasing a new version, and the release notes need to be copied to at least a few places.

Additionally, you might not want to list all of the features in the app in the documentation. I mean what’s the point? And especially, don’t do this in multiple places and services. Don’t do like I did.

Documentation

This project has taught me the importance of good documentation. Even though it was mostly me alone working on this project, I would have benefitted from more documentation about the different aspects of the project.

This has become especially clear now when the project has not been in active development, but instead, I have been working on some random bug fixes every few months or years. I have even ended up having a bit of discussion with myself via some TODO comments in the codebase as you can see from the screenshot below or check the lines in the codebase in GitHub with this link.

Something that I have learned is the importance of the following levels of documentation:

Readme, instructions how to get started etc.
Testing instructions
Release / deployment instructions, with enough detail
Good commit messages
Clear and good code comments where needed

Managing Internationalization

I wanted to provide my application in multiple languages. For this, I have been using Transifex which is a great tool for crowdsourced translations. I received surprisingly many contributions from the community in the Transifex project. The application is available in 10+ languages translated by more than 20 volunteers. A few weeks ago, someone requested to translate the app into Polish.

However, handling the different languages adds to the maintenance overhead of the project and makes the release process slightly more complicated. This is something I should have automated but never did.

The Importance of a Supportive Community

For a platform to become successful, it is important to have an open and active community. I think the Sailfish OS developers community has been super helpful and there have been multiple people helping me a lot when I have had trouble with this project. Special shoutout to kimmoli and coderus for their help!

Refactoring

Refactoring should happen in small phases and not in a big bang refactoring. I ended up working on a way too large refactoring that touched most of the codebase and I almost ended up giving up on it. The end result was a bit nicer codebase but with some newly introduced bugs. I never continued the refactorings further, so now the codebase is not as nice as I would like it to be.

There is a lot of duplication in the codebase, so one option would be to start getting rid of those piece by piece and after that start transforming the codebase oto a more recommended way of building UI applications in Qt. However, I most probably never will do this. Instead I would probably start from scratch and build a new version that would be better designed both from the technical perspective and the UX and UI perspectives.

Don’t Start with Advanced Features Too Early

I made the mistake of implementing some advanced features such as email export, database export, CSV export and import as well. This led into more complex maintenance since I had to try to keep this in mind when thinking about fixing something or adding more features. Everything needed now to be backwards compatible and I tried to make sure importing a database dump would work even across different versions of the application.

To be honest I’m not even sure if this worked all the time, and I’m not sure if any of the users ever used these features. Lesson learned: focus on the core features.

App Development Is Different from the Web Development

Web development is relatively easy in terms of updates. Most of the websites don’t utilize lots of local data on the users device. Of course some exceptions exist and LocalStorage is an example of local data stored on a user’s device that sometimes needs migration etc. Most websites, you can deploy a new version at any time, and your users will get the new version when they load the page again.

In the world of mobile applications, you can’t just deploy a new version. What you can do is to submit a new version of the application to be reviewed. After approval, it will be available for your users to download from the app store if they wish to do so. Sailfish OS has no option for automatic updates and there is no way to force the users to upgrade.

My application is working fully offline with a local only database. This is a good idea from the users perspective, but could easily become a hell to maintain. In some cases having the data stored on a central server could be considered as a nice benefit. Especially if some database migrations need to take place.

On the web, pages may break easily due to changes in the backend API and some users may be keeping a tab open for months (true story BTW!). On the web, this is not considered critical, and the user is often told to try to refresh the page, close the browser and try again etc. On the native side however, an app crashing is usually considered more critical.

Fun Facts about the Project

To end this blog post, I’d like to share a couple of fun facts about this projec.

Fun Fact 1

Here’s a fun fact about how I built a solution for getting notifications for comments and reviews even though the platform did not have a support for this.

When submitting an app to be reviewed and added to the Jolla Store, there is or at least used to be a critical feature missing in the process: notifications. You would not get notified when your app got either approved or rejected. Additionally, you would not receive any notifications when users commented or rated your application in the store. The only way to notice that someone had commented or given a new review was to actually open the app store on a Sailfish OS device and check the comments there.

However, if you log into harbour.jolla.com where the applications are submitted for review, you can see the amount of reviews and likes etc. for your own applications. At that time I did not realize there was an API also available for this data, so my solution was a bit more complicated than necessary.

My Solution for Notifications

I had a Selenium script running on an interval of 15minutes. The script would

Open harbour.jolla.com
Log in
Go to my applications
Scrape the amount of reviews, likes etc. from the HTML
Write those into a file
Compare with previous values
If they had changed, send a IRC message to myself with a text saying something like “Working Hours Tracker has received a new comment”

On my server where I was running my irssi IRC instance, I had a perl script running that would send an XMPP notification to myself for all the private messages I received.

On my mobile phone, I had an XMPP client installed, that would notify me of new XMPP message.

When receiving a message, I would then see that I need to open the Jolla Store and check the comment from there

My solution was complicated but it worked all the time, except from when it didn’t. Sometimes I needed to go kill some of the processes on the server after it started running out of memory because some Firefox processes were left running in the background for some reason. I never spent time on investigating why this happened, I simply killed those processes every once in a while.

Additionally I extended this solution to save the amount of downloads, likes and active installations into a database and I was able to visualize those on the web page using Highcharts. The solution is not working anymore, but it was visible on the homepage for this project: wht.olpe.fi.

You can see how it used to look like in the screenshot below:

Fun Fact 2

Huge part of the users for my app seem to be from Germany for some reason. See this tweet about WHT download stats in OpenRepos:

Olavi Haapala 🇫🇮

@0lpeh

WHT download details from #openrepos
Whats up with Germany? Almost as many as Finland...
#jolla

19:19 PM - 15 Jan 2015

The Most Important Lesson Learned

I think the most important lesson this project has taught me is that you learn by doing. I think the fact that I can laugh at the code I wrote a few years ago is a good sign because it means I have learned a bunch of things and if I were to start a similar project now, I would make better decisions and make new kinds of mistakes – but not the same stupid mistakes again.

This project has been supported by the Futurice Open Source sponsoring initiative: Spice Program. In fact, this project probably helped me land a job at Futurice in the first place.

Cheers for reading the post. This ended up being my longest blog post so far and I still would have wanted to write more, but I guess It’s time to publish this.

Do Everyone a Service by Writing Good Commit Messages

Olavi Haapala — Tue, 16 Mar 2021 10:22:00 +0000

Author’s Notice

Somehow, I feel like the importance of good commit messages can not be overstated and a good commit message is worth its bytes weight in gold. Writing good commit messages is also easy to forget or may feel like a waste of time, which it isn’t. That’s why I wanted to write this blog post.

The Anatomy of Good Commit Messages

This blog post does not aim to be a definite guide for how to format your commit messages. In fact, that’s totally irrelevant in my opinion. I think it’s one of those conventions that does not matter. You can read my thoughts on that topic in my previous blog post:

Conventions Don’t Matter – What Matters Is Consistency

Olavi Haapala for Futurice ・ Feb 2 '21 ・ 3 min read

#conventions #teamwork #practises

However, here are some of the aspects that make a good commit message. Taking these points to use will make you or your colleagues thank you later.

The Why

The most important thing to convey in a commit message in addition to what was changed is the why something was done in a certain manner. Quite often I look at some code changes and try to wonder why things were done like this even if git blame would say that it was me who did the change. In these cases, simple commit messages like Use LibraryA instead of LibraryB give no additional value. Instead of a better commit message in this case could have been something like this:

Use LibraryA instead of LibraryB in order to avoid a bug in LibraryB

There is a bug in LibraryB, that causes undefined behaviour in certain cases when the user clicks this button. Using LibraryA instead fixes the issue since the library does not use the problematic library “xyz” under the hood like LibraryB does

For more information, check the release notes: xyz.github.io/releases/1.2.3

As you can see, this commit message tells the future you or anyone else bumping into the commit message the what and most importantly the why at a quick glance.

Commit Messages Are Like Documentation

Good and clear commit messages act like documentation. Writing documentation is always painful, right? But if you do it immediately when commiting your code changes, it’s not that big of an effort.

In order to learn more about the importance of clear commit messages, you can watch this amazing talk by my colleague and friend, Juhis: Contemporary Documentation.

However, don’t forget the actual documentation as well as adding clear comments in your code. I think that if a solution requires either a longer explanation in a code comment, it should also have a longer explanation in the commit message and vice versa.

Good Commit Messages Makes Bisecting Easy

As I wrote in one of my previous blog posts about git bisect, git bisect is a powerful tool for quickly finding problematic commits. In those cases a clear commit message helps as well. Read the blog post for more.

You can read the blog post here:

Git Bisect Is Your Friend in Need

Olavi Haapala ・ Jan 25 '21 ・ 3 min read

#git

Commits Should Only Contain Related Files and Changes

I like to think of commit messages like labels that are added to certain lines of code forever. The latest labels are often easily visible in editors and when using git blame or even in UIs like in GitHub.

This is why it is important to keep in mind that a commit should only contain changes that are related to the actual change described by the commit message. It feels weird to have some files changed with a commit message that has nothing to do with that particular file.

Of course, this could happen by accident as well, if using git add . or similar solution to include all the changes. I think it is important to always inspect what is going to be added and usue chunks. This is extremely easy with a graphical user interface for git. I’m personally using GitKraken and I’m happy with it.

Git blame, despite its negatively loaded name is a useful tool for inspecting the history of a file and you should be able to see why certain lines have been changed if good commit message practices have been in use. The why is the most important part, and even in projects where you are the only developer, after some time, you’ll have no clue why something was done in a certain manner. Even more so, if someone else is looking at your code and commits.

Commit Messages Are Not For Your PR

Commit messages are not supposed to be used to communicate something that happens in your pull request. In fact, PRs have nothing to do with git itself, but rather something that tools like GitHub and others have come up with and added to their set of tools. Some people might even wonder what’s the difference between git and GitHub.

A large pull request should be split into smaller, meaningful commits with clear commit messages. This makes the reviewing easier and faster. However, try to keep the PRs small and avoid huge long lasting PRs.

Something That’s Obvious Now Is Not Obvious Later

When working on some features in a codebase, you have quite a lot of implicit context and knowledge in your head. This is something that may be obvious while working on it, but later on it probably isn’t obvious anymore. When coming back to some piece of code after a while, you’ll want to see clear and informative commit messages.

Commit Messages Can Be Used for Announcements

Jani Eväkallio recently published an interesting open source tool called git-notify, which makes it possible to use git commit messages for announcing some important changes to your team members or even your future self.

Check it out at:

jevakallio / git-notify

🙉 📣 Communicate important updates to your team via git commit messages

I think this is a brilliant idea and may save a lot of frustration and time in larger development teams.

Sometimes You Don’t Care and That’s Okay

Sometimes it’s okay to not care. Such cases include doing a hobby project in your free time and you are the only developer ever going to touch that codebase.

However, you never know what happens and suddenly you might not be the only person contributing to the codebase anymore. This is when good commit messages may save a lot of time and frustration by acting like a good documentation. Additionally, when the time passes and you are not actively working on the codebase, you most likely will forget some aspects of it. This is when your own commit messages turn to be helpful for you when you are trying to look at a piece of code and you have no recollection of why things were done in a certain way in the past.

The Rules of React Hooks - And How We Messed up

Olavi Haapala — Mon, 15 Mar 2021 10:22:25 +0000

React Hooks have quickly become the recommended way to handle component local state and side effects in React function components. Getting started with hooks is quite straightforward, but you might need to change the way you think about your components, especially when it comes to the useEffect hook.

This blog assumes you know the basics of React Hooks – if you don’t you can find out more here – and will dive a bit deeper into how they should be used. I’ll also be sharing a bit about the mistakes we made and how it took us nearly a month to fix the mess.

React hooks - easy to learn, hard to master

React Hooks were launched in React version 16.8 and they have quickly become a popular way to handle components, local states, and component side effects, among other things. They’re quite easy to get started with, but they're challenging to master properly – you have to learn to think a bit differently compared to React’s traditional class components and lifecycle hooks, and there are certain rules that you have to follow.

Some examples of hooks and how to use them

The simplest hook is the useState hook, which takes as an argument the initial state. useState is a function that returns an array with two items in it: the first is the actual state and the second is a function that sets the state. Another of the built-in hooks is useEffect, which is for running side effects in your React function components. For example, if you have a shopping cart with a button to add a banana, when a banana is added you might want the document title to be updated as a side effect. With useEffects, you define the dependencies – you can think of it like defining the array and how often you want to run the function. If you leave it as an empty array, it will only run once, after the initial render; otherwise, it will run after every render of the function, unless you define the dependencies. So, when the state changes, React just calls this function again. And from a useEffect function, you can return a cleanup function.

To understand the useEffect cleanup, try this analogy from Ryan Florence. Imagine you have only one bowl in your house to eat cereal from. You wake up in the morning and eat cereal whether you're hungry or not – that's the initial render. Time passes, the state changes, and you become hungry again. Now you need to clean the bowl because it's dirty from when you ate earlier. You clean it up first and then you eat again – this is the same as React running a cleanup before running the effect again, which is also why when a component is unmounted it runs the cleanup when it's removed.

Easy mistakes to make with React hooks

I’ve just mentioned two of the most important hooks, but let's talk a bit about typical mistakes with hooks. The first mistake you might make when you start using useEffect is you might forget to add the dependency array, meaning your effect will run on every render. Why is this a problem? Imagine you're doing a fetch in your useEffect. This would happen on every render, causing a new render because something was changing the state of the component. This would make it render again, causing an infinite loop. Another typical mistake you can make when you start refactoring useEffects is having a useEffect that depends on the state that is saved inside it. This causes another infinite loop, but you can solve it by doing functional state updates instead of traditional useState calls.

Rules to follow – and what happens when you don’t

The simplest rule is that hooks must start with “use” – I think React will even warn you if you try to do something that doesn't start with use. Next, call hooks should only be used at the top level of your function components, so you can't nest them in statements. This is because React only relies on the order of the hook calls, so for every render you should call the same number of hooks so that React knows which hook is which. Finally, you can only call hooks from React functions. This should probably be self-explanatory, but when I started using hooks, I wanted to use them in some utility functions, and I realized quickly it just isn't possible. ESLint is very useful to check these rules. There are two plugins that I can recommend: react-hooks/rules-of-hooks and react-hooks/exhaustive-deps.

So where did we go wrong? In the beginning of a project, we used TSLint instead of ESLint, because at that point TSLint wasn't deprecated yet, so we thought it would be fine. We had the React Hooks plugin installed and enabled, but for some reason we forgot to enable the React Hooks rules, so TSLint wasn’t actually checking the rules. We had it there for months and didn't notice, and because we didn't know the rules well enough, we didn't notice that our code was piling up into a huge mess.

At that point we changed from TSLint to ESLint, which was already a big refactoring PR because we also made our rules stricter. At first we had the exhaustive deps rule disabled after the refactoring, as well as one huge component where we had to add the ESLint “disable React’s rules of hooks” line, because the file was just too large to be fixed in that PR. And then I started fixing this mess and enabled the exhaustive deps rule and decided to just do what ESLint tells us. I thought it would take me a couple of days, it ended up taking more than a month to fix just the exhaustive-deps violations, including causing some regressions in production.

Lessons learned with React

The most important thing we learned was to keep it simple, in both your React code base and in hooks. Even though you can make huge effects, it's better to split them into multiple effects – and if this makes your component code looks ugly, you can abstract it away into a custom hook. Secondly, you should always enable ESLint rules and enforce them, and it’s best to have ESLint in your editor. At this point I’d also like to recommend Betterer – a cool tool that can be used in legacy projects and in larger, ongoing projects to stop you from making the project worse over time. You add tests that make sure you stop doing the wrong things and forces you to do better in future. This is handy when you don’t have time, energy or resources for these kinds of huge refactoring PRs.

I also learned that custom hooks are quite cool. They are a really useful way to share code and logic between components. And during this refactoring I've learned when to use useReducer and when to use useState. useState is fine, but if you have more than, say, three useStates and you need to change a few of them at the same time but they're relying on each other, then it's better to use useReducer with one state object and then dispatch actions that update the state.

Where to learn more about React and React hooks

If you want to learn more about hooks and the rules of hooks, React’s official docs are amazing – they explain the rules and why you have to follow them. If I had read them to start with I wouldn’t have made the mistakes I did! I’d also recommend taking a look at Dan Abramov’s blog, overreacted.io. A complete guide to useEffect is interesting, as is React as a UI Runtime, and how are function components different from classes will teach you some important differences.

This blog was based on one of my Tech Weeklies talks. You can listen to the full episode here.

You Will Never Be Done with Accessibility

Olavi Haapala — Tue, 09 Mar 2021 09:55:00 +0000

Making a website accessible is challenging and requires a big effort from the whole team including developers and designers. Ideally, accessibility should be considered already at the very early stages of a project instead of trying to “fix” it afterwards when in fact it’s already too late.

Accessibility is not a simple binary feature of a website either. You can’t say that one website is accessible and another one is not. It’s actually all about how well and easily accessible the website is.

Creating accessible websites may sound like a straightforward engineering task, but it requires a lot of attention to details and knowledge about how the web works and how different users browse the web. However accessibility is not rocket science, if you take it into consideration all the way from the very beginning of the project including the design and concepting phase of the project.

Additionally, you can get quite far by using semantic HTML and native input elements (don’t forget labels!). They are mostly designed to be accessible to everyone. However, this blog post is not about how to create an accessible website.

Accessibility Is Never Done

You should never think that you are done with accessibility. Saying your site is accessible and you are done with accessibility is like saying that cutting the grass is done. It will soon need to be cut again.

Photo by Jonas Weckschmied on Unsplash

There will always be some parts of the project that could still be improved, some technologies might evolve and the conventions and guidelines may change over time. The dependencies of your project may introduce new bugs and accessibility violations and you yourself or anyone else on the team may accidentally make the accessibility worse. Projects are evolving over time and you should keep a close eye on accessibility in order to not make it worse.

The same goes for web performance. In this sense, web accessibility and web performance go quite nicely hand-in-hand. Making a website perform well and fast means it becomes more accessible to people on low-end devices or slow networks either temporarily or permanently. Similarly to accessibility, web performance should also be monitored and improved over time in order to not make it worse.

Automating Is Not a Silver Bullet

So, if web accessibility and performance are important and you should be keeping an eye on them over time, surely there is a way to automate everything, right?

However, there is only so much you can do with automation and automatic testing for accessibility violations. Some of the issues can only be solved by manually testing and sometimes only by interviewing your end users that use your service and have some disabilities.

Learn More

If you want to read more about automatic accessibility testing and its limitations, read this blog post by my colleague, Eevis

Automated Accessibility Testing Is a Good Start - But You Need To Test Manually Too

Eevis (she/her) ・ Feb 14 '21 ・ 7 min read

#a11y #webdev #react #testing

JavaScript Should Be Your Last Resort

Olavi Haapala — Tue, 02 Mar 2021 08:36:00 +0000

JS Is Your Hammer

When working on modern frontend web development, using your favorite framework of choice, it can be sometimes tempting to solve all the problems with JavaScript. Sometimes this happens unconsciously as JS is what you mostly use in your day-to-day development work.

This is similar to the situation described by Abraham Maslow in 1966:

I suppose it is tempting, if the only tool you have is a hammer, to treat everything as if it were a nail.

– Wikipedia: Law of the instrument

Photo by Fausto Marqués on Unsplash

Note: In this blog post, I’m only talking about JS even though I’m mostly using TS in my projects – it ends up as JS after compilation anyways.

What to Take into Account When Implementing UI

This mindset of using JS for everything causes unnecessary processing that needs to be run on your end users’ devices as client-side JS. All the JS resources on a website need to be downloaded, parsed and executed by the web browser. This is quite often the cause of slow and unresponsive websites on low-end mobile devices or slow network speeds.

How You Should Be Thinking Instead:

Can this be done in HTML?
If not, can I solve it with HTML + CSS?
And if nothing else works, the solution probably requires a minimal amount of JS in addition to HTML and CSS

This way of thinking is not about what is easiest for you as a developer. You may be a JavaScript focused frontend developer, and solving most of your problems with it feels natural for you. However, you should be thinking about your end users. Client-side JS is the single biggest problem when it comes to web performance. You can read some of my thoughts on web performance from my other blog posts. You can find some links at the bottom of this blog post on my personal blog.

1. Can This Be Done in HTML?

Plan and implement the basic structure and semantics of the feature in plain HTML without any extra styles and using native HTML elements and functionality. If some additional styling or features are needed, go to step 2.

2. Try to Solve It with HTML + CSS

Use CSS to apply the additional styling or animation that is required, still keeping the semantics and accessibility in my mind. If some additional interactivity is required in the particular piece of UI you are building, go to step 3.

3. Use HTML + CSS + JS

Add the minimum amount of JS required to fulfill the requirements. Keep in mind that something that can be solved without JS should probably be solved without JS.

When you’re done, show your code to your colleagues and let them review it. Perhaps there is still something unnecessary parts in your code, that could be solved without having a client-side JS cost for your users.

Simple Example

This problem applies to almost anything in web frontend development, but here is a simple practical example that should help me prove my point.

Imagine you are working on a React project, and you are working on a feature that has some UI parts that should only become visible after a certain delay, let’s say after 2s.

Using React Hooks

If you are used to solving your problems with React and Hooks, your initial solution could look something like this:

const [thingVisible, setThingVisible] = useState(false);

useEffect(() => {
  const timeoutId = setTimeout(() => {
    setThingVisible(true);
  }, 2000);

  return function cleanup() {
    clearTimeout(timeoutId);
  };
}, []);

return thingVisible ? <section>Here's a thing for you!</section> : null;

This is fine and works. Probably you notice no difference in performance either on your hyper powerful developer machine. And probably, there is no real performance issue in this case. But imagine if these pile up and suddenly you would have tens or hundreds of similar unnecessary JS computations to be run on the client-side or some larger and longer executions that are taking place.

Using HTML + CSS Animation

Using CSS, you can animate content to appear on the page with a delay using CSS animations and animation-delay. This is supported by all browsers and could even have a better end user experience as you could fade the content in or use any other ways of making the content appear more smoothly.

The HTML:

<section class="fade-in">Here's a thing for you!</section>

The CSS:

.fade-in {
  opacity: 0;
  animation: fadeIn 2s;
  animation-delay: 2s;
  animation-fill-mode: forwards;
}

@keyframes fadeIn {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
}

Don’t Use CSS for What You Can Do with HTML

Similarly, don’t do something with CSS that you could and should be doing in HTML.

An extreme example of this was that we had accidentally been using margins to separate two words from each other, instead of using a space in between the words!

This was obviously not a good idea from at least the following perspectives:

It might not follow the font size, letter spacing etc.
It is not needed, waste of effort and processing
If someone would need to copy the text, there would be no space in between the words

Frontend Development Is Not Easy

Web frontend development is not an easy topic to master. It is something you can get started with quite rapidly, but mastering it requires some level of experience and understanding the whole picture in order to be able to solve the right problems on the right level using the right tools. Solving something on the frontend has many levels and details baked in it.

Additionally, you’ll need to understand when a problem should be solved on the backend instead of the frontend for various reasons such as performance, usability or maintainability among others.

However, keep in mind that sometimes you don’t need to try to reach for a perfect solution and something that works might be good enough to be shipped to production and to be used by your end users.

Modern and Accessible Marquee Clone with TailwindCSS

Olavi Haapala — Tue, 23 Feb 2021 09:20:00 +0000

What Even Is/Was marquee?

Marquee is a deprecated HTML element that renders scrolling content. For more information, check the MDN page for marquee for more details.

It is not recommended to use the <marquee> element even though it might still work and additionally in modern days, you rarely need anything like this. However, sometimes you do and you might need a solution to this using modern web technologies.

Example <marquee> if your browser still supports it:

Here's an example for you, that should render this text as an element with scrolling text if your browser still supports these.

If you see nothing above here, it means dev.to is understandably escaping the content and rendering HTML tags from user input is not supported. You can check this post on my personal blog in order to check how the <marquee> would work on your browser.

Problems with Marquee

Not very user friendly – many people do not like scrolling text.
Deprecated and not matching the modern web design.
Stressful for the user who might miss some of the content and has to wait for the scrolling to start from the beginning.
Not respecting user’s preference for reduced motion. Many people will feel physically ill or sick when a website has (too many) moving elements on it.

DO NOT USE JS FOR THIS

When implementing a <marquee>-like element using modern technologies, please bare in mind that you (probably) won’t need JS for the job outside of maybe using something like React to render the element.

My example implementation is using React in a Next.js project, but I chose not to use JS to achieve the wanted result. It is often better to try to achieve as much as possible without JS whenever feasible. JS is the root of all performance issues and especially when used for something that can be achieved using HTML and CSS only. I will probably write another blog post about this topic at a later point in time.

Marquee Using CSS Only

To achieve a rolling text effect, the only thing we need is some HTML and CSS. The effect can be achieved with CSS animations.

Basic Solution With HTML + CSS

In order to animate the text and get the feeling that the text “wraps around” and goes on infinitely, we need to add the elements twice to the DOM and animate them starting from different positions. First element will start from 0 and go all the way to -100% and the other one will start from 100% and go to 0. If we animate both elements with the same duration, the first element will be reset back to the initial position when the second element reaches the starting point, thus the user won’t notice when the animation starts over again.

Here is a basic example snippet to achieve a <marquee> like effect using HTML and CSS:

HTML

<article>
  <div class="wrapper">
    <ul class="marquee">
      <li>Item 0</li>
      <li>Item 1</li>
      <li>Item 2</li>
      <li>Item 3</li>
      <li>Item 4</li>
      <li>Item 5</li>
    </ul>
    <ul class="marquee2">
      <li>Item 0</li>
      <li>Item 1</li>
      <li>Item 2</li>
      <li>Item 3</li>
      <li>Item 4</li>
      <li>Item 5</li>
    </ul>
  </div>
</article>

CSS

article {
  border: 2px solid red;
  overflow: hidden;
  white-space: nowrap;
  width: 350px;
  display: flex;
}

.wrapper {
  position: relative;
}

.marquee {
  animation: marquee 5s linear infinite;
}

.marquee2 {
  animation: marquee2 5s linear infinite;
  position: absolute;
  top: 0;
}

ul {
  display: flex;
  list-style: none;
  padding-left: 0;
}

li {
  margin: 8px;
}

@keyframes marquee {
  from {
    transform: translateX(0%);
  }
  to {
    transform: translateX(-100%);
  }
}

@keyframes marquee2 {
  from {
    transform: translateX(100%);
  }
  to {
    transform: translateX(0%);
  }
}

And here’s a link to a codepen with the above content and a functioning version of it:

Codepen.io basic marquee example

Using TailwindCSS

Tailwind config here:

extend: {
  animation: {
    marquee: 'marquee 30s linear infinite',
    marquee2: 'marquee2 30s linear infinite'
  },
  keyframes: {
    marquee: {
      '0%': { transform: 'translateX(0%)' },
      '100%': { transform: 'translateX(-100%)' }
    },
    marquee2: {
      '0%': { transform: 'translateX(100%)' },
      '100%': { transform: 'translateX(0%)' }
    }
  }
}

And now we can use these animations using the classes that Tailwind generates for us:

<article class="flex whitespace-no-wrap overflow-x-hidden">
  <div class="relative">
    <ul class="flex animate:marquee">
      <li class="m-8">Item 0</li>
      <li class="m-8">Item 1</li>
      <li class="m-8">Item 2</li>
      <li class="m-8">Item 3</li>
      <li class="m-8">Item 4</li>
      <li class="m-8">Item 5</li>
    </ul>
    <ul class="flex absolute top-0 animate:marquee2">
      <li class="m-8">Item 0</li>
      <li class="m-8">Item 1</li>
      <li class="m-8">Item 2</li>
      <li class="m-8">Item 3</li>
      <li class="m-8">Item 4</li>
      <li class="m-8">Item 5</li>
    </ul>
  </div>
</article>

And here’s a link to a codepen with the above content and a functioning version of it.

Accessibility Aspects

Having animations and motion on a webpage can make some people feel physically ill or sick. That’s why it is important that we as developers provide the users a way to opt-in to reduced motion. Many operating systems provide on option on the system level to set a prefers reduced motion setting, and you as a web developer can use that for reducing the motion using the prefers-reduced-motion media query.

Tailwind has these built-in as utility classes called motion-safe and motion-reduce which we can use to make the <marquee> clone accessible and user friendly. In order to use these, make sure you add this to your Tailwind config:

variants: {
  animation: ['motion-safe', 'motion-reduce'];
}

Then we can enable the animation only if the user has not preferred reduced motion by using the class motion-safe:animate-marquee and motion-safe:overflow-x-hidden.

<!-- As a fallback we show scrollbar but hide overflow and animate it in case:
    - The user has not preferred reduced motion
    - The user's browser suppports prefers-reduced-motion media query 
 -->
<article
  class="flex whitespace-no-wrap overflow-x-scroll motion-safe:overflow-x-hidden"
>
  <div class="relative">
    <ul class="flex motion-safe:animate:marquee">
      <li class="m-8">Item 0</li>
      <li class="m-8">Item 1</li>
      <li class="m-8">Item 2</li>
      <li class="m-8">Item 3</li>
      <li class="m-8">Item 4</li>
      <li class="m-8">Item 5</li>
    </ul>
    <ul class="flex absolute top-0 motion-safe:animate:marquee2">
      <li class="m-8">Item 0</li>
      <li class="m-8">Item 1</li>
      <li class="m-8">Item 2</li>
      <li class="m-8">Item 3</li>
      <li class="m-8">Item 4</li>
      <li class="m-8">Item 5</li>
    </ul>
  </div>
</article>

As another usability and accessibility improvement, we might want to pause the animation on hover by setting the animation-state to paused. In this case we use a class name to indicate clearly that when hovering over it, we pause the animation on any of its children. Why do we need to do this? Because if we would only pause the animation when hovering over the element that has either marquee or marquee2 animations, the other list, which at that point of time would be non visible, would continue animating and soon appear on the element. This would not be a nice experience as the texts would overlap.

.pause-animations-on-children-on-hover:hover * {
  animation-play-state: paused;
}

Learn More

Here’s nice blog post on this topic by Josh Comeau:Accessible Animations in React.

Optimization

In our case we wanted to start the animation only after receiving data from an API. In this case we could use the will-change attribute to hint the browser that this element will be animated.

.will-change-transform {
  will-change: transform;
}

See the MDN page for more information and please note the huge note there.

Important: will-change is intended to be used as a last resort, in order to try to deal with existing performance problems. It should not be used to anticipate performance problems.

Based on this note, I think I should actually not have used this, but instead measure the performance and only improve it if there are some performance problems.

Fun Fact

Even though <marquee> is deprecated, it’s really not gone, the functionality is currently available in most web browsers but it’s not recommended to use it as it can be removed any time in the future without a warning. See the MDN page for marquee for more details.

When I started drafting this blog post and used <marquee> in the title and excerpt of this post, the page contents started scrolling to left and I had to fix this by escaping the title and excerpt before rendering them as HTML.

So, remember to escape your content, especially if it’s input directly from your users.

I first thought this blog post would be about implementing this in React and TailwindCSS, but as I mentioned, my solution uses no JS, so the framework used for rendering the HTML does not matter.

An open PR is the first 90% of the job – the other 90% remains

Olavi Haapala — Tue, 16 Feb 2021 10:41:00 +0000

Foreword

You probably have heard about the ninety-ninety rule in software engireening. This post introduces my variation of the rule.

The point of this blog post is not to scare you, but rather to help you understand why estimation is difficult and often fails. You may need to update your mental model for estimations because it’s too easy to not consider all the non-coding related work in estimations. Unless you are a seasoned developer with lots of experience in estimating, my advice is to try to stay away from estimating if you can.

The First Thing You Should Learn About Estimations

Estimating is hard.

Estimating is challenging.

Your estimates will be too low.

Estimating is difficult.

Estimating is guessing.

Your estimations will be wrong.

Double or triple your initial estimates – quite often π is a nice multiplier and there are some theories behind this as well.

You should probably try to avoid having to do estimates if possible.

If you have to estimate, try to take into account the unkown unknowns.

Did I mention estimating is hard?

How Hard Can It Be?

Quite often, you might be foolishly thinking that coding is the biggest part of creating new features or fixing existing bugs in a product. Sadly, this is rarely the case. In many cases, it’s the other way round and the actual coding is the smallest part of the total amount of work. Investigations, debugging, testing, QA, communication, and documenting tend to take most of the time.

Based on Personal Experiences

This blog post is mostly based on my personal experiences in contributing to different open source projects and also my experiences at work related projects. Additionally, I have some experience in doing estimations for my side business, where I provide tree removal services on my free time. My customers often want a fixed price for the job. It is often difficult to estimate how long time it takes to remove a tree. Many times, the seemingly biggest job of felling the tree is actually the fastest part of the job and the rest takes surprisingly long in comparison. Even though the field is completely different from software development, I can see some similarities in how challenging the estimations are.

The Ninety-Ninety Rule

I believe the ninety-ninety rule was originally meant as a joke, but it has some level of truth in it and in surprisingly many cases the final fixes and fine tuning takes way more time than expected – quite often the other other 90% of the time.

Here’s a direct quote from the Wikipedia page about the Ninety-ninety rule:

The first 90 percent of the code accounts for the first 90 percent of the development time. The remaining 10 percent of the code accounts for the other 90 percent of the development time.

— Tom Cargill, Bell Labs

My Variation of the Ninety-Ninety Rule

My variation of the ninety-ninety rule is as it says in the title of this blog post:

An open PR is the first 90% of the job – the other 90% remains.

— Olavi Haapala

It is often too easy to only think about the time spent coding a fix or a feature when doing estimations. However, based on my experience, that accounts only for the first 90% of the time – the other 90% remains. After you have coded something and opened a PR, there’s still quite a lot of work remaining before the task is completed. This is also why you should be focusing on finalizing one task all the way to prod before starting a new one.

Abandoned PRs Are the Worst

I have personally opened quite many PRs in open source libraries without taking into account the amount of work that remains after you open a PR. You most probably will receive some feedback about your code changes and need to modify the code. Additionally you might need to add more tests and documentation, and communicate about the changes. All of this, even if small changes and casual communication takes quite a lot of time and mental energy if nothing else. Some of my PRs have been left abandonded due to lack of time or motivation to work on the remaining 90% of the work.

Opening a PR and then abandoning it might be a huge burden for the maintainers. They need to keep communicating with you, checking up with your PR and waiting for you to contribute to the remaining 90% of the work.

So, when thinking about opening a PR to a open source repository, remember that the other 90% of the work still remains even if you have coded a fix or a new feature. Coding is “easy”, but getting code finalized, approved, tested, merged, and deployed is more challenging. And don’t forget the feedback and possible changes from your users after you have deployed a change or a fix.

Maintenance Cost

In this blog post, I don’t even talk about the costs and work after a fix or a feature has been shipped to production. That’s a whole other story and this blog post would be too long if I would include that as well. However, that’s a real fact and you should consider the total cost and effort required including the maintenance after deploying something.

Things to Take into Account

When working on a bugfix or a new feature to a codebase, there are a few things you should take into account. I’m here focusing mostly on open source libraries, but the same probably applies to most projects.

First of all, check if someone has had the same issue and if it is already fixed or a simple workaround exists. Usually, you would start from the project’s issues. If you’re not lucky, you’ll have to post a new issue and explain the problem and mention that you are willing to work on a fix for it.

Of course, these instructions may vary depending on the project you are contributing to, so take your time and read the contributing instructions which quite often are found either in the README.md or the CONTRIBUTING.md file. And if the instructions are missing, maybe that’s something you can and should contribute to first.

Now, that you have communicated the issue and your intent to fix it, you can start the actual coding work. Try to follow the existing code style in the code base and avoid fancy abstractions that are not readable by others. Keep in mind that code is mostly read instead of written so readability is more important than the amount of code lines.

What’s Next

After you have implemented a fix, there are a few more things to take into account:

Remember to write tests or update existing tests to match the new output. And especially in cases of bug fixes, write a failing test first before fixing the bug. This way you can make sure your fix works, and that the bug should not appear again in the future because your test should stop that from happening.
Write clear and descriptive commit messages with meaningful and logical chunks of code. I could write another blog post about the importance of good commit messages, but meanwhile you should watch this amazing talk by my colleague and friend, Juhis: Contemporary Documentation
Write a clear description for your PR with possible screenshots before and after, explanations for why things were done in a certain way, and instructions for testing your code changes.
Check that your code has no conflicts, and double check that your changes still work. If something worked yesterday, it does not mean it works today.
Respond to feedback on your PR even if you disagree or if you don’t need to change anything. Thank the reviewers. If you receive change requests, implement those changes and go back to step 4.
The next steps depend on the project: in some projects you merge your changes yourself and deploy to prod, but in many cases you need to wait for the maintainers to merge and release a new version.

Closing Words

I hope this blog post was at least somewhat useful to you.

If you did not pick up anything else from this blog post, at least you can keep in mind that estimating is hard and you should avoid doing it if you are able to choose.

Writing Blog Posts Using Speech-to-Text

Olavi Haapala — Tue, 09 Feb 2021 05:25:00 +0000

TL;DR

No, at least based on my experience, I won’t be using this approach in the future. Writing with a proper computer keyboard with 10 fingers is in my experience way faster and less error prone than speech to text, based on this experiment. This is true in my case because I’m lucky enough to have two healthy and functioning hands and I’m able to use a proper keyboard and computer.

I’m not trying to downplay the usefulness of these kind of technologies as way to make writing more accessible and easier for different people and different use cases. I occasionally use speech-to-text for writing short messages as well. The technology is also getting better and better over time, and there may be better solutions available that I haven’t heard about.

Getting Started With Speech to Text

The other day, I had this idea of drafting blog posts on my mobile phone by using the speech-to-text keyboard input. This would allow me to draft blog posts easily while doing something else at the same time, or simply while lying on a sofa. So, I wanted to give this a go, and this is how the two first sentences looked like. I started drafting this blog post a few weeks ago and I have no clue what I tried to say here:

my phone and this is how did people with.

Taylor dayne I had an idea what is

Not a good start! However, after a few sentences, the results improved, and the rest of this blog post is mostly drafted by speech-to-text with some manual editing and fine tuning afterwards.

The Actual Content Drafted Using STT

The other day, I had an idea about writing blog posts by dictating them using my phone. So, now I’m trying this out. I will be talking to my phone and drafting the post like this. This seems to not be working well. I’m on my Android phone OnePlus 7T Pro and I’m using the Google keyboard as it can listen to me and write it down. Of course, I have to admit that I’m not a native English speaker and that’s why it might not recognize my words in the way I pronounce them. Also, somehow it seems like this starts working better when I focus on this when I look at the screen and try to speak a bit more slowly and clearly and think about letting the phone get what I mean.

Not Ready to Give up Just Yet

So, I’m not ready to give up yet. I will try to finish this blog post and my idea is that maybe I’ll post the raw output or at least a couple sentences from it so you can see what kind of output my phone produced for me. In theory this should be a powerful way for drafting blog posts because you could quickly draft some notes – dump your brain to text and then you can edit it later and iterate on it and then publish it when you have finalized the text.

Wishful Thinking

At least based on this test, this will be pretty useful too for me. On the other hand, if I would be talking in more technical terms, I think the keyboard really won’t be able to recognize all my words. I haven’t looked in more detail in the Google keyboard how this works but it somehow feels like it might be learning more if you’re using it. If I actually start using this now, it may learn more about my words and even the technical terms I would be using.

Any Tips for Me?

Have you tried drafting your blog posts by using speech-to-text? How did it work for you? How does your writing process look like?

Are there some better tools for this purpose that I should know of?

Feel free to reach out to me.

Conventions Don’t Matter – What Matters Is Consistency

Olavi Haapala — Tue, 02 Feb 2021 09:26:00 +0000

Consistency Is the Key

When working in a larger development team, it’s important to have clear conventions for various aspects of the project. Some of the conventions could be about the team’s ways of working, such as code review processes, git practices and other topics. Most time consuming debates usually are about code style and coding conventions. I personally think that the conventions really don’t matter. What matters is that everyone follows the agreed conventions consistently.

This is also why code formatting tools, such as Prettier have become widely adopted and popular. Prettier puts an end to the non-important discussions about coding style, such as using or omitting semicolons or trailing commas and other useless discussions which are quite typical discussion in JavaScript or TypeScript projects. Prettier takes care of formatting the code, and in your code reviews, you can focus on things that matter.

Why Conventions Are Needed

However, there’s a lot more into conventions than code formatting. Especially when using general purpose languages such as JavaScript or TypeScript or libraries such as React. There often are multiple ways of handling different scenarios in the code base. Sometimes developers working simultaneously on different branches implementing different features, but technically speaking solving a similar problem, may end up solving the problem in vastly different ways. Often, it is impossible to say that one of the ways is wrong and the other one not. What matters is that the coding conventions are consistent. This is why the team needs to agree on the conventions and then enforce them and train everyone in the team to follow the agreed conventions.

Don’t Blindly Copy Best Practises

There are a lot of examples of long form best practices and conventions written up, which you can check out and adopt in your team as it suits your team. Something that works for others, may not work in your cause though. It is always best to discuss together and agree on the conventions that work for your team and project. However, I would argue that the conventions themselves are unimportant. The only thing that matters is that everyone is following the same conventions and doing so consistently. Over time, the code base should remain somewhat uniform to the extent it is possible.

You may think that is a bad idea, and stops innovation and adopting new trends and technologies. I dare to disagree. New conventions can be agreed on, and when a new convention is agreed on, it should be used in the codebase from that day on. Either by refactoring the whole code base to follow the new convention, which should be doable if the previous convention was followed carefully, or by using tools such as phenomnomnominal/betterer to incrementally adopt a new convention, and stop anyone from adding new code that does not follow the newly agreed convention. It is equally important to document the agreed conventions and keep the documentation up-to-date over time in addition to making sure everyone on the team hears about and understands the agreed conventions.

Conventions Should Not Be Carved in Stone

A team’s conventions should be evolving as the team evolves, learns something new, and new members join the team. It is impossible to agree on perfect conventions that would cover all the future aspects taking into account all the things that are going to happen in the project, in the tech field and in the world. A good example of this is how many teams used to work mostly co-located at offices, but suddenly, due to COVID-19, had to switch to working fully remotely. This has forced teams to evolve their ways of working and conventions in order to adapt to the new situation and continue collaborating in an effective manner.

What Works for Your Team

How are the conventions agreed on in your team? How do you document your conventions? What has been the most challenging topic to agree on? I would be interested to know that. Comment below or comment on this Twitter thread or if you wish, you can contact me with DM or in any other way that suits you best.

Git Bisect Is Your Friend in Need

Olavi Haapala — Mon, 25 Jan 2021 20:55:00 +0000

Debugging Is Hard

Sometimes you have to debug bugs that are confusing and you may have no clue why something happens. It may feel impossible to identify what is going on and why. Quite often in these cases, it would be helpful to know when did something start going wrong. In other words, it would be helpful to identify which particular commit caused the issue you are investigating. Not to blame anyone, but in order to find the problem and fix it. In fact, quite often it’s you yourself who have introduced the issue, so blaming won’t help as it never does.

Git Has Superpowers

Git is a powerful tool, but some of its powers are underrated or unused. Maybe because not many people know how to use the more advanced or rarely used features of git. In this blog post, I’m going to explain how git bisect can be used to quickly identify a problematic commit. With the help of git bisect, you’re often able to save a lot of manual investigation when debugging challenging issues in your codebase.

When to Use Git Bisect

Git bisect is a powerful tool and I recommend trying it out, especially if the following conditions are met:

You have an issue in your codebase
You don’t know what caused the issue but you want to fix it
You are able to find an older commit where the issue does not appear

How to Use Git Bisect In Practice

Run git bisect start
Find and check out a commit where the issue happens. Most probably your latest commit has the issue you are investigating
Run git bisect bad to mark that commit as bad
Randomly check out an older commit and make sure the particular issue does not appear in it
Mark that commit as good by running git bisect good
Run git bisect run

Git will automatically checkout a commit for you using binary search algorithm to effectively help you find the problematic commit. Try reproducting the issue, and mark the commit as either bad or good: git bisect bad|good. Now, you should see something like this in your terminal output:

git bisect good
Bisecting: 183 revisions left to test after this (roughly 8 steps)
[7aa559c43a988b0c9e189411f785f0e753a48721] Merge remote-tracking branch 'origin/whatever-branchname into another-branchname

After you have done the marking enough times, which should not take too long. Git will be able to tell you which commit first introduced the particular problem. In my case the output looked something like this:

➜ git:(d76efd76e) ✗ git bisect bad
d76efd76e08307f75e4cd1fca4d5f332b3933753 is the first bad commit
commit d76efd76e08307f75e4cd1fca4d5f332b3933753
Author: Olavi Haapala <email@redacted.com>
Date: Tue Oct 27 11:34:28 2020 +0200
>
Upgrade next from 9.4.4 to 9.5.5
>
package.json | 2 +-
yarn.lock | 1139 +++++++++++++++++++++++++++++-----------------------------
2 files changed, 561 insertions(+), 580 deletions(-)

In this case the particular problem was introduced already a few months ago, when I upgraded Next.js from 9.4.4 to 9.5.5. Notice, how this also highlights the importance of good commit messages. I was immediately able to see what this commit was doing and could take a look at the release notes for Next.js to investigate why this issue got introduced. It would have taken me hours and hours to manually go through all the hundreds of commits after this bug got introduced. Git bisect saved me from doing that.

Almost Done

After you have found out the cause for a problem, the work is almost done. Fixing a known issue takes almost no time compared to hunting a problematic piece of code from a larger code base. Of course this is not always true, but in most cases it is.

Save Even More Time When Using Git Bisect

If you want to save even more time when using git bisect to hunt down a problematic commit, you can let git automatically check if the commits are bad or good. After the command git bisect run, you can give a command to be run which determines if a commit is good or bad. In some cases it could be running your tests or in other cases you could make a script that looks for something else that goes wrong. Git bisect opens up a world of possibilities beyond manually checking different commits and PRs and trying to guess when a problem first started appearing.

Here’s a screenshot of a tweet I sent a few years ago about enjoying the magic of git bisect:

If you haven’t used git bisect before, please give it a try. I promise you will save some time after you learn to effectively use it.

My 2020 in Review

Olavi Haapala — Thu, 21 Jan 2021 10:19:00 +0000

Author’s notice

I have not been actively publishing new content in my blog for a longer time now, due to trouble with my blog setup, failing to rewrite the blog from scratch, and on top of that, you know, just 2020 being 2020.

Now, that I finally have my blog setup working again and as I’m trying to ramp up my content production, I thought it would be interesting to write about how the past year has been for me and how the year 2021 is looking like at this point of time. As this is a more personal blog post, I thought it would be nice to add some pictures as well. Enjoy!

2020 Was a Historical Year

2020 was a weird year in many ways. I’m quite sure, the last year was a weird year for everyone. And we all know about the pandemic and other unexpected things that happened, so I will not be talking about those. In stead I will try to focus on other stuff, but the pandemic has had an impact on almost everything.

Work

2020 was a busy year for me at work. We had just finished a longer site renewal project in March 2020 and launched it to production, when the whole pandemic situation started massively hitting Finland as well. And in addition to that we had an even larger project starting up due to an acquisition that came to us as a bit of a surprise. I ended up working too much in 2020 and did not have too much time for stuff like open source and personal projects.

Working From Home or Anywhere

I have been working fully remotely since the beginning of March 2020. Working from home feels pretty good to me as I live a bit further away from the office. Now, that I don’t need to commute to work every day, I save almost 2 hours everyday. On the other hand, working from home seems to easily lead into working more than I should. Starting the workday earlier than normally is easy without having to commute to work. Ending the workday is more difficult at home than leaving the office after a day at work. I used to work remotely every once in a while earlier as well, but working full time remotely is quite different.

Events in 2020

Events have turned into online events, and in the beginning they felt interesting and fun. Now, there seems to be a lack of interest in online events due to the lack of social interaction, which happens in physical events when you bump into random people and start discussing various interesting topics. Despite all the events being held online, I have still managed to present quite many times in our weekly tech event called Tech Weeklies. You can learn more about Tech Weeklies from this blog post in The Futurice blog. Naturally, not all of my talks are public due to non-public content, but you can see links to the recordings in YouTube of some of my talks in the talks page.

Learning by Presenting

Presenting is interesting as it forces you to learn more about the topic you are going to present about. Even if you think you know something, only if you are able to explain it to others, you actually know it. In many cases, I have had to look into the basics again, in order to be able to talk about that topic. Presenting is fun and I recommend you to try it out if you haven’t. Please note though, that the first time presenting might not be super pleasant as you get nervous about it. It will get easier over time and through practice. After a few presentations, you can start concentrating on the audience and not only on what you were supposed to say next. I personally find presenting in person easier than presenting remotely. When presenting in a virtual event, you don’t see your audience and you get no feedback from them during your presentation.

Side Business

In September 2019, I founded a company called Iltametsuri Oy. The company is my side business/hobby for cutting down trees on my free time. During 2020, I did about 30 smaller or larger gigs, which is surprisingly good in my opinion. This job acts as an interesting balance for the (home) office work where I stare at screens all day long. Getting outside and doing something physical gives me a lot of energy and motivation.

Most of the company’s gigs so far have been for friends and colleagues, but increasingly I get new contacts due to my online precense and a Google ad I’m paying for. My initial ad budget was 3€/day but I recently increased it to a whopping 6€/day. During the first fiscal year, all of the revenue (and a bit more) has been invested on buying the best available tools, some of which you can see in the image below.

Vacation

On the other hand, 2020 was a nice year. Despite busy and stressful times at work, I was able to have more than 8 weeks of vacation last year! Not all of it was paid vacation, some weeks were balance leave, but still. And when I say vacation, I mean vacation as you can see from the below screenshot of my GitHub contributions. By the way, almost all of my contributions last year were on work project. I did not do much open source work in 2020. Last summer I enjoyed the Finnish nature more than any previous years in my life.

Vacation Routines

My routine for starting a vacation includes closing Slack and work email on my laptop, trying to avoid using my laptop at all, and deleting Slack and work accounts from my mobile phone completely. The only way my supervisor or colleagues could reach me on my vacation would be by calling me, but who even makes normal calls nowadays? Not even once have I been interrupted on my vacation due to work.

2021

The year 2021 is off to a promising start. We have interesting new challenges at work, I started the year actively by doing a lot more cross country skiing than I normally would do since we finally have proper winter with lots of snow even in southern Finland, and on top of all that, I have more time and energy for writing blog posts.

My Goal for 2021

My goal for 2021 is to start producing more content, including more tutorial videos. At least with the blogging, I’m already on a quite nice track.As several people have said, consistency is the key. So, my goal is to start consistently producing interesting content in the form of blog posts, presentations and videos.

Who knows, if in 2021 we could again have physical events such as conferences and meetups face to face. That remains to be seen, but let’s hope for the best.Stay tuned for more content in my blog this year! You can also send me wishes on topics that you would like me to write about.

Server Side Rendering: Why We Have Gone Full Circle

Olavi Haapala — Wed, 11 Dec 2019 06:40:00 +0000

Author’s notice

This blog post is based on one of my recent tech talks “Why is SSR relevant in 2019” and represents my limited view on the topic.Please bare that in mind when reading this blog post.My view on the history of the web may have mistakes and is certainly not covering all aspects.In the beginning of this post I’m trying to explain some of the key concepts and how the web works before diving deeper into why Server Side Rendering is relevant today.

I almost got carried away and did not get into writing about the main topic until late in this post, so please feel free to jump over the first half of the post and start reading from 4 Reasons Why SSR is Highly Relevant Today.

This blog post is highly opinionated, read at your own risk!

How the Web Looks Like Today

The web as we know it, consists of web pages and applications built with a huge variety of technologies.However, there is one thing all web pages have in common, HyperText Markup Language (HTML).In the end all of the web technologies end up creating the webpage content as HTML that gets rendered on the screen.Most of the web pages also use Cascading Style Sheets (CSS) for styling and JavaScript (JS) for dynamic functionality.More and more modern web pages are built as JS Single Page Applications (SPA) that rely heavily on the JS runtime for rendering content on the screen and handling the application logic and navigations.This does not necessarily mean writing all the code as JS directly, but there are multiple compile-to-js languages and tools available.Most commonly known is TypeScript (TS).

Even though all web pages are quite similar from technical point of view, there are huge variations in the page “weights” as in how heavy and slow performing the different web pages are.Performance is directly connected with how likely your users are to return to your web page.If you are running an e-commerce business, and trying to sell something, a bad performance will directly affect your sales.

Sadly the situation does not seem to get better over time even with the evolution of technology and web development tools.One could easily assume better tools and tech would make the web a better place for everyone, and most importantly for the increasing amount of users browsing on mobile devices.

In fact, based on HTTP Archive, the amount of web traffic from mobile and tablet devices surpassed the traffic from desktop devices already in 2016 globally.This can bee seen in the below image.

Based on the HTTP Archive stats, web pages got ~20% heavier and slower on almost all metrics when comparing 2017 to 2018.Most of the increase in page weight and slowness can be explained by the increasing amount of JS on web pages.On the other hand, many web pages are a lot more complex nowadays than they used to (or need to!) be.

If you like to read more about heavy webpages and the biggest reason for slow webpages, go ahead and read The Cost Of JavaScript In 2018 (sorry, Medium link!) and The Cost of JS in 2019.

Some Definitions

Let’s look at some of the commonly used terms and their definitions before diving deeper into the main topic of this blog post.

Server Side Rendering

In a Server Side Rendered (SSR) web page, the web server returns an HTML document that already contains the content as HTML.The browser will render the document contents on the screen whenever it receives the document and parses it from top to bottom.

Client Side Rendering

Client Side Rendering on the other hand refers to a technique where the server only returns a skeleton of the application in the HTML document.The HTML only acts as a template and has a link to the JS application bunldle, which the browser downloads, parses, and excecutes.The JS application then renders the contents by hooking itself into a root div that is part of of the server rendered HTML contents.Usually this means something like:

<body>
  <div id="app"></div>
</body>

Isomorphic Rendering

Isomorphic Rendering on the other hand, refers to a technique where both SSR and CSR are combined in a web application.The server renders the document contents as well as the initial application state as JSON in the HTML.After rendering the SSR content on the screen and loading the JavaScript bundle, the JS application then reads the initial state from the server rendered response and boots up the JS application.This phase is called rehydration, the static server rendered HTML document gets hydrated into a JavaScript SPA.This approach tries to achieve the best of both worlds by achieving a fast first paint because of SSR content and fast SPA navigations after the application has been rehydrated.

A Short and Simplified History of the Web

The web was invented for about 30 years ago.In the beginning everything was fully server side rendered web pages.First web pages were documents containing text and links, images were added a bit later.More and more interactivive elements were aded as part of the web when JavaScript invented.Interactive elements suc as Flash, Quicktime, RealPlayer, and Shockwave came along.Still, at this time most of the web pages were built using SSR with mostly PHP and friends.

JS Fatique

A multitude JS libraries started popping up such as MooTools, jQuery, and Backbone.These allowed developers to create interactive web applications more easily using JS instead of Flash or other old school tools.Later on, Angular.js was published and in around 2014 React was published.This started a new era in the web development scene.Suddenly “everyone” was doing client side rendered JS based SPAs.This caused web pages to get heavier and slower.Something needed to be done.

Progressive Web Applicationss got introduced.Along other features, they provided an additional cache layer on the client level using Service Workers.However, in my opinion this is a wrong solution to the problem of slow web pages.

Back to the Roots

Recently the web development community has started realizing that going full on with client side rendering was a mistake and ruined the web performance, especially on cheaper and slower devices.Now, suddenly “everyone” is talking about SSR again and many frameworks and platforms provide solutions for that.This is a good direction from web performance point of view.

Accelerated Mobile Pages

Accelerated Mobile Pages (AMP) is Google’s iniative for making the web faster on mobile devices.I think the initiative in itself is good, but I don’t like the way Google tries to enforce it and take the ownership of the web and its contents by serving pages from their own cache servers.Google is also misusing its huge position in the market by prioritizing AMP pages in Google search results.Sadly most of the people are using Google for searching, which forces companies to start considering using AMP in order to achieve good positions in search results.Due to the above mentioned reasons, I would not recommend supporting or using AMP at all.

AMP in itself is a good library for creating web pages, because it limits the possibilities in which you are able to create horrible user experiences on the web.

Even AMP recently announced a revolutionary new technology called SSR in the AMP library as you can see in the below screenshot of Ricky Mondello’s sarcastic tweet:

I agree with Ricky, that this is ridiculous.We have had HTML and SSR for 30 years, what do we need AMP for?

Okay, time to move to the actual topic of this blog post.

4 Reasons Why SSR is Highly Relevant Today

Here are my 4 reasons for using SSR today.

1. Performance

Web pages that are rendered only on the client side tend to have quite slow time to First Paint (FP) and First Meaningful Paint (FMP), because the browser has to first download, parse, and excecute the JS bundle before it can paint the contents on the screen.The below screenshot tries to visualize what these different metrics means.

Image source: User-centric Performance Metrics.

In order to achieve a good user experience, try to move these events as close to the left as possible, meaning as fast after navigation start as possible.Additionally Time To Interactive (TTI) is an important metric, because before that moment in time, your users can’t start interacting with the interactive parts of your site.

This is where SSR has its biggest win.With server rendered pages, the browser is able to paint the document contents on the screen immediately when it has received the document and goes through the contents of it.With this approach, it is possible to achieve

2. Search Engine Optimization (SEO)

Google and other search engines most probably will not run the JS on your web page when indexing the web.There are rumours that Google is running the JS, but with a 2 weeks delay.For most of the businesses where a good SEO is critical, a 2 weeks delay is not acceptable. ~~And as a cherry on top, Google reportedly runs your JS with an ancient version of Chrome, which is even worse than IE9.~~ Edit: This was not true anymore, Google bot now uses the latest version of Chromium.

So, if you care about good SEO, use SSR.However, if you have a fully functional SPA and don’t want to invest time in implementing SSR, there are ready made services that does the SSR for you.At least Netlify has SSR as a service that you can start using if you are hosting in Netlify.

3. Accessibility

Accessibility is about making it possible for everyone to access and understand the contents on your webpage.Accessibility is about performance as well.A slow webpage is not accessible to everyone, only those on high-end devices and fast network connection speeds.

Some people even prefer to browse the web without having JS enabled.If you SSR your main content, your web page will be accessible even withou JS enabled.If your application uses SPA navigations when the user clicks on links, don’t worry, they will work fine as normal links that have been working for 30 years already without JS.

4. Not Everything Needs to be an App

Remember, that even though creating web applications is popular, not everything nees to be an application.In many cases, a simple HTML based SSR web page is enough.Say, a landing page for a newly started company.You don’t need to build it as a SPA application, especially if you build it as a one-pager with navigations happening in that same page.There’s a revolutionary technology for achieving just that, and it’s called anchor tags or <a>.So, please use the platform #usetheplatform.

Final Words

No matter, what technology you use, remember to consider your real end users over a better Developer Experience (DX).In the end, the only thing that matters is that your users are happy.In most of the cases that means having a fast experience even on mobile devices and flaky connections.By optimizing your web application or web page for slower devices and slower networks speeds, you will end up making it a better experience to everyone.Similarly, by focusing on making your application accessible, you will end up making it more usable to everyone.