DEV Community: Futurice

Bringing Back the Technical Excellence: Rules of Thumb for Effective Software Lifecycle Management

Niko Heikkilä — Fri, 19 Nov 2021 07:58:16 +0000

In software, legacy code is a code that runs in production.

Don't you love the defeatist attitude of this quote? You might have stumbled upon it on many occasions. But, sadly, it is not too far from the truth.

There are many definitions for legacy code. I've settled to define it as the code we are afraid to change, yet we need to. The code whose developer experience converges asymptotically to zero over time.

Complexity as a Driver for Legacy Code

Without realising it, we tend to create software like we construct buildings. The hard way: layer after layer, too late to look back and improve things in retrospect. We fail to keep software soft as we lock the details in place with complexity in both design and implementation.

Complex design often comes directly from complex business requirements. We might rewrite a service en masse without criticism only because the customer asked us to do so. We are keen to ask what kind of software they want us to deliver while the more pressing question is: what problem do they want us to solve?

Complex implementation, therefore, is a direct consequence of complex design. However, the effects of complex implementations become more detrimental via their ability to feed themselves and keep on growing during the software lifecycle.

The common culprits for complex implementations are the following:

teams are not abiding by the technical excellence and software craftspersonship — also known as having immature senior engineers in the team
too high (100 %) utilisation rates keeping everyone as busy as possible therefore stifling innovation
severe blindness towards the wastes in the development process
allowing the unplanned work (e.g. production incidents) to stall the team's throughput by holding planned work hostage
working through tasks in isolation (one-person silos) and not sharing and integrating code daily
accepting too much work, and as a result, cutting corners under pressure to get tasks done

All of the above contribute to unhealthy codebases, but the fastest way is to cut corners regularly.

Often, we have a situation where our time and budget constraints seemingly do not allow us to deliver our best software craftspersonship. Unfortunately, cutting corners under pressure from stakeholders is a temptation many of us are not prepared to resist.

As a result of cutting corners, our codebases typically lack automated tests, technical documentation, and sometimes even styling. So, you may only wonder, what could be the reason for not even having the chance to add a style guide to the project. Time? Carelessness? Lack of skills? All of it?

The above are the definitive signs of a legacy codebase. But why should we care about legacy code?

Because most legacy codebases still deliver heaps of value to their users. However, what they lack is cost-efficiency. The cost of developing new features has risen to extreme heights due to emerging complexity. What took three hours to implement a year ago might now take three or more days, especially if the team compositions have been changing in-between and silent (undocumented) knowledge runs wild.

Having worked in software lifecycle management for a significant portion of my career, I have gathered a set of practices to fight back the costs emerging from complexity.

In this post, I present a brief — constantly evolving — guide on gradually bringing back technical excellence and driving down development costs.

I will focus mainly on writing tests and documentation, the two most crucial things regarding missing technical excellence. Other important factors like increasing security, observability, and accessibility of a product are not discussed in this guide (yet).

Increasing Cost-Efficiency Through Automated Tests

When investigating an insufficient test coverage, it's easy to let the Sunken Cost Fallacy tell us that we shouldn't bother with automated tests at this point in the project.

We judge that the costs of covering the entire codebase with tests are already too high and thus not worth the investment. Besides, the people who originally developed the application should have paid attention to writing tests from day one.

How do we fix the situation? I've found it helpful to traverse the Test Pyramid from top to bottom.

We start by migrating our definition of releasable through automated end-to-end tests that usually test the user interface flows. Next, we sink into delivering new features, fixing defects, and refactoring code by leveraging fine-grained tests and test-driven development. Ultimately, this guides us to build coherent technical documentation through well-defined test suites.

End-to-End Tests

When the codebase has zero automated tests, it usually means that all the acceptance testing before a release is done manually.

It is not unusual to manage test cases in software like Jira or PractiTest. Within these tools, a special QA team designs and runs the tests, compare the actual test outputs to expected, and notifies the release team of any critical issues they uncovered.

Meanwhile, developers are watching Youtube waiting for the bug reports to arrive.

If we need to manually verify that our user interfaces are functioning correctly, the automation of said test cases is easy. Instead of clicking through pages in the browser, we can add these steps as scripts using tools like Cypress and Playwright.

Yes, but... our product doesn't contain a browser interface. We have a set of legacy APIs instead.

Suppose we want to verify that our backend integrations return the expected responses to given requests, it is helpful to use a technique called Golden Master, also known as characterisation testing. If you have ever used snapshots when verifying that the shape of a complex object or a structure of a UI component did not change, you are familiar with the Golden Master technique.

"Rather than revert to the Guru Checks Output antipattern, however, I take a snapshot of the last-known acceptable output — I call that the golden master — and save it for future use. When I run the test again, I compare the output to the golden master, and if they match, then the test passes; if they don't match, then the test fails." — J.B. Rainsberger.

Yes, but... how do I sell the initiative of adding tests? It must cost us a fortune to have developers study automated testing techniques and then migrate our specialised test cases.

Fortunately, expenses are modest if we carry out the migration in tiny steps.

We can order our test cases by priority. Users being able to sign in to a self-service portal is naturally a higher priority than the business contact information being rendered in a specified order. The stakeholders are happy to know that by automation, we have eliminated the chance of human error.

Alternatively, we can find out what test cases consume the most of our time. For example, clicking through the whole e-commerce flow from adding products to a shopping cart, filling in details, choosing a payment method, and eventually checking from the confirmation page that the order was processed is a significant time sink. We should record these steps and automate them. The stakeholders are happy to know that we have eliminated the time cost of manual testing and saved additional bandwidth for solving other problems by automation.

Yes, but... now that we are automating everything, does it mean I have to fire our QA team?

No, you don't need to fire your testing specialists. Instead, they can free up their bandwidth and expertise from mundane regression checks before releases to continuous, investigative, and exploratory testing through automation.

Each sprint should include a feasible amount of test case migrations. When planning the next sprint's contents, everyone must understand that our velocity drops slightly because we will not deliver as many new features right now. However, after a few sprints, the automation benefits kick in, and the velocity restores to normal levels and even higher.

Having a stable suite of automated end-to-end tests gives us a preliminary safety net. It guards us against breaking the whole application while we are changing it.

However, refactoring and thus keeping the codebase in prime health is still potentially dangerous. For that, we need to dig deeper...

Fine-Grained Tests

At this point, your most valuable revenue flows are covered with high-level end-to-end tests. The problem is, when one of these high-level tests fail, there can be multiple causes for it.

When high-level end-to-end and integration tests fail, it's similar to a fire alarm buzzing you that something is burning somewhere in your city, but you don't know what it is. Alas, the only way to find out is to follow the smoke.

Perhaps the worst trait of end-to-end tests is that they are slow. When a test run takes a long to complete, I'm incentivised to skip running tests frequently. When I don't run tests for each tiny change, I risk adding more and more risky changes into the batch, taking away my chance to safely change the codebase.

Enter fine-grained tests, more often referred to as unit tests. Practical unit tests verify a single behaviour of the system under test. Thus, they fail for one and only one reason.

Furthermore, we can run unit tests fast side-by-side with code changes using a watchdog functionality. Whenever I write new code, tests related to my changes are run automatically. Thus, I get instant feedback telling me if I'm straying from a safe path. It's precious while refactoring: if my changes pass the tests, I commit them and carry on — otherwise, I revert my codebase back to the last working state.

Yes, but... we don't have any unit tests in our codebase right now. Where should we start?

Sprinkling unit tests here and there in the codebase doesn't motivate us. It's best to focus on adding tests to parts of the codebase you have changed frequently and recently (frecency).

We write an expectation for every new feature, witness it fail for the right reason, and finally write enough code until the expectation is satisfied.

For every new defect raised, we should write an expectation exposing the fault and then write code until the expectation is satisfied and the defect has vanished.

Test-Driven Development and Refactoring

The technique I described above, also known as test-driven development, is the easiest and safest way to introduce new features to our codebase in a controlled manner. You are free to disagree with me, but I dare you to find me a more effortless and safer way.

Unfortunately, many developers still take a step backwards and judge you when they hear the acronym TDD. They may decry it as a mantra, or something sinister practised within a religious cult. To those people, we can tell that programming is always about setting expectations for your code. Without TDD, these expectations are stored in your head and verified with your human senses. With TDD, the expectations are held as executable tests and confirmed by the computer. Do you really think the human brain is more effective?

That being said, TDD is not a silver bullet for every situation. Nevertheless, I like the points Kent C. Dodds writes on their blog post. Precisely, I embrace the notion of not using TDD while doing exploratory coding.

I, too, have found out that when I'm trying to figure out how a library or a framework works, I tend to hack some code together and learn it through exploring. Hacking is not an issue unless every task you work on becomes a feeble attempt at exploratory coding. Such is prone to happen when we don't split nor refine our tasks to concrete implementation details. The more I need to duct tape my code, the less incentivised I'm to write tests first, and my main driver is simply to make the code work.

Let's remember that TDD is not a testing tool. Instead, it forces us to design our code before writing it. If we never pay attention to good design, our codebase will eventually become a rotten cavity that only gets worse before a dentist needs to operate the whole tooth with a root canal, or in our case, rewrite the code.

Yes, but... using TDD, we can't write tests for the existing code by definition, right?

When we are writing tests for the existing production code, we often find it difficult. As a result, our design likely contains serious flaws, usually caused by a lack of continuous refactoring, which has not played a significant role due to a lack of tests as a safety net.

Fortunately, we can practise test-driven development also for the existing code by following the steps below.

In the codebase, locate the code (behaviour) you want to test
Comment out the code as if it never existed in the first place
Write a failing test
Start restoring the commented out code line by line until the new test passes
If necessary, write another failing test and make it pass
Remove (do not comment out) all the code not required for the tests to pass
Refactor until the code satisfies your taste

There are many good resources written about refactoring. I tend to follow the four rules of simple design by Kent Beck:

make the tests pass
refactor until the intention is clear
remove duplication where feasible
remove everything not needed to satisfy the first three rules

More succinctly: test, refactor, remove, and repeat.

If the codebase is extremely convoluted as a consequence of lousy engineering, we find this process difficult. In those cases, instead of commenting out old code, we should consider writing a new module or class from scratch. Then, when we are ready, we can swap it with the old implementation helped by the interfaces defined in our type system. Doing so leaves us the possibility of quickly reverting back to the old implementation if things go wrong.

Most importantly, writing tests side-by-side with both the existing and new production code takes away the reason to ask how much writing tests cost. The cost of writing tests is now embedded within the feature development.

In some projects, I've seen teams creating separate tickets for writing tests and refactoring. Doing so, the developers think they get proper permission for these tasks, but they actually look as if apologising for following the quality standards of their craft.

Differentiating tests and refactoring from feature development is a huge red flag and makes us developers look unprofessional. We must never allow ourselves to think a feature is done unless we have proved it with tests. Respectively, refactoring is a mandatory continuous practice, which must never require explicit permission.

The Boring Part: Document All the Things

Let's assume that through rigorous testing and refactoring efforts, our codebase is in better shape now. End-to-end tests ensure we can release safely, and fine-grained tests provide we can rapidly develop and refactor new features.

What do we miss? Documentation!

When studying a codebase for the first time, I often reach for three different types of documentation:

How do I install and run this application locally?
What features does it have, and how do I use them?
What past decisions have affected the design of this application and the way it works today?

Read Me, Read Me!

We should ensure we have a README file in the project root for the first task. This is the front page of your documentation in modern version control systems, which people consult first. As a bare minimum, it should contain the following information.

How to install the application
How to start the application
How to test the application manually
How to run the automated tests
How to deploy the application
How to contribute to the codebase
Who to ask for support in case the documentation can't provide answers

Executable Documentation

The second task, however, might surprise you. Having covered our codebase with automated tests, we actually have the relevant technical documentation right there, and we can even run it — aren't we the lucky ones.

End-to-end tests document how the users interact with our application and how the client applications interact with our backend systems. When written clearly and concisely (see behaviour-driven development), every developer can quickly grasp the basics.

Fine-grained tests document how our internal interfaces are used and how public methods are called. Without fine-grained tests, we would have to read the entire source code to understand how to call its public methods, what inputs they require, and what kind of outputs they produce. By looking at well-defined tests, it becomes evident like reading a user manual.

Yes, but... my excellent IDE shows enough information when I hover my cursor over the method name. So why do I need more documentation?

Indeed, many state-of-the-art omnipotent god-given IDEs can also display the intent and signature of methods by hovering over their name. However, our code often contains intricate handling for edge cases and errors, which are not apparent by looking at the type signatures. It bears repeating that type systems, despite their value, never have, and will never, be a substitute for proper tests and documentation.

Architectural Decision Records

The third task is perhaps the most exciting one. Despite our best efforts, we can't know what we don't know. Even with codebases that could be a little more than a year old, we tend to find ourselves in peculiar waters.

We may ask ourselves, how did this class come to be? Why is this state shared between these components? Why does our database table contain an index for this column? Why do we require an API key for all our public REST APIs?

Surely we can figure out the answers to the above questions ourselves, or more traditionally, by asking other developers. However, wouldn't it be nice to read the answers explained to you in plain text, ideally next to the source code?

Yes, but... I can just as quickly run git log and check the history from there.

Stop right there! Commit messages in version control systems are great for capturing and explaining the motivation behind micro-level changes such as renaming a variable. However, they perform poorly for significant architectural changes spanning across tens or hundreds of small commits.

Some developers are keenly obsessed with keeping the version control history linear to tell a logical narrative of changes between points A and B in time. I admit to doing it myself from time to time. Other developers like to squash merge entire feature branches so that one commit equals precisely one feature. In most situations, both approaches come with tradeoffs that make them more harmful than beneficial.

Thus, we should use Architectural Decision Records instead.

ADRs capture a single decision that has significant consequences towards the design and implementation of the product for the foreseeable future. Typically, they include but are not limited to:

title of the decision
status (proposed, accepted, rejected, or superseded by another ADR)
context (why did we have to discuss this?)
decision (where did our discussion lead us?)
possible consequences (what later impacts did our decision have?)

ADRs work well with internal meetings, and therefore we should set a requirement that no architecture meeting takes place unless a decision or proposal is produced.

Yes, but... aren't the ADRs useless for us? I mean, who can't remember what we discussed yesterday or last week?

You might feel like it now, but try telling that yourself in six months. I can assure you that when enough time has passed in a project, even the code you wrote is indistinguishable from someone else's.

Conclusion

If you, like me, have worked in maintaining the software in the later stages of its lifecycle, I hope you have enjoyed this post and found pieces of wisdom in it.

The bottom line is that we should not run away from legacy codebases. Granted, I can name a dozen more exciting tasks than trying to get an old application without tests or documentation up and running. However, that is not for us to decide. All we have to decide is what to do with the code that is given to us.

Keep calm and carry on!

Photo by Cesar Carlevarino Aragon on Unsplash

Being a Good Developer: Tips for an Effective Code Review

Niko Heikkilä — Sat, 02 Oct 2021 14:26:19 +0000

Hey! An earlier revision of this post described how to survive the world of pull request workflows. However, since then, I've grown more convinced that asynchronous development is among the well-known root causes why software teams struggle to ship working code fast. Thus, I've decided to rewrite this post to reflect the way I currently think, enjoy!

Many of us have been there. A software project with significant business value should ship to end-users as soon as possible. But, unfortunately, the budget has run over. Management is throwing a furious fit. Developers are doing their best to sustain and control damage by explaining that the features are being reviewed and tested, but all they need is a little more time.

Rapid feature delivery is impossible when code reviews become a blocker, which they often are because of our inability to shift left (move events earlier in the process instead of later).

Some developers' comfort zone is buried under noise-cancelling headphones working on a feature isolated from the rest of the world. After a couple of days, the feature is "finished", and a pull request is submitted for peers to scrutinise. However, an effective code review can't occur because the changeset is made of inconceivable hunks of code totalling over 1000 changed lines.

Feeling the insufferable pressure from management, another developer takes a quick glance at the changes, writes "looks good to me", and approves the pull request. Finally, another developer spots a couple of minor design issues and apologises for nitpicking while commenting. The reply is a famous line:

"Yeah, let's fix this later when we have time."

Legacy code is born when we fail to build quality in.

All those moments where we play a safe bet and write another page of technical debt explaining how we had a tight schedule. Surely, we can pay back the technical debt later. So in a sense, we can, but we won't.

I've done this too many times and always felt ashamed, profoundly questioning my professionality. This post will explain how you can avoid these pitfalls and make code review a pleasant part of the development experience.

Ask for a Review Before Committing

The greatest thing you can do to improve your team's performance is to integrate feedback into your work early and often. In practice, this means you shouldn't delay improvements to a post-development phase.

Many professional teams have been influenced too heavily by open-source development workflows fashioned by GitHub, where all the changesets must be submitted as pull requests. Certainly, pull requests have become a disastrous plague for many teams: they promise a sense of security but deliver only bottlenecks and constraints in return.

Pull requests have their place in open-source development where trust doesn't exist. They are also helpful on those occasions where deployment to a temporary preview environment is needed. However, in other situations, pull requests do little to facilitate the code review experience, often making it worse.

When the development happens asynchronously, developers work on their tasks and are forced to wait until their peers are available for review. Naturally, this incentivises starting new tasks before previous ones have been finished. It's a trait rooted in our mind that we should keep ourselves busy, lest a judging eye of the management might find us slacking and not working. However, the more tasks we start, the more context-switching penalties we suffer, and the slower our velocity become.

Fortunately, the great minds of the Extreme Programming community have had a solution to this for a long time: test-driven development and pair/mob programming. To achieve the most effective form of code review, we should use linters to check our code style, write the minimum amount of code to make tests pass, and finally use ~~a rubber-duck~~ a teammate to verify our design. All this should happen at the same time, in the same space, on the same computer.

I've written extensively about the benefits and pitfalls of pairing, so suffice to say here that the best code reviews take place instantly after a single line has been written.

The bottom line is that code review doesn't need online tools. Instead, discuss code face-to-face (in person or through screen sharing) and resolve any issues in real-time. Defects are best fixed when it's cheapest and fastest: before creating a commit.

Split the Changes by Concern

The unfortunate truth is that defects will occur despite our best intentions. Therefore, it's equally important to limit the scope of our changes by concern. That means working in the smallest feasible batches. These can be integrated into the codebase as independent micro-commits without breaking a thing.

Defects are much easier to find from micro-commits, and they are effortless to revert where needed. For example, I've lost count of how many times git bisect has saved the day because I've used micro-commits.

Practising Continuous Integration dictates that we should push to the trunk at least daily — I prefer multiple times a day. However, developers sometimes reject this notion stating that their changes are too large and risky to integrate now. Hence, they stash their batches in branches, allowing them to grow in size and become more challenging to review.

A reinforcement loop where we are forced to write large batches because we're afraid of integrating reveals a malodorous design smell. The task you took wasn't correctly broken into subtasks, and it likely contains dependencies to other developers (or teams) work. Unfortunately, it's too late for us to fix lousy design during a code review, but we can monitor and improve for the future by limiting the scope and writing smaller user stories.

Invite the Right People to Review

If you have written a fresh new algorithm for solving a computational problem, have it reviewed by someone who genuinely knows about code performance and the Big-O notation. In addition, people with impeccable CSS grid skills will serve you better when you're designing those fancy new UI changes later.

Often team compositions vary greatly. Sometimes teams are built from generalists (jacks of all trades) and sometimes specialists or deep experts in different areas. In the case of specialists, inviting more than one person to review is helpful. Doing so facilitates knowledge sharing and allows the team to level their specialities, guiding them to fluidly grow as generalists.

Expecting more than one person for review might tempt us to walk our code through multiple rounds. However, what we need is a live mob review, again without tools.

For example, changes to APIs handling sensitive data may require additional attention for security details. If the team has a security specialist, have them lead this code review and invite the team to learn.

Likewise, the review for introducing a new design system to improve mobile responsiveness could be led by the group's front-end specialist.

Grab the Mentoring Opportunity

In the past, I've used code review as a strict gatekeeping and controlling tool to prevent lousy code from entering the codebase. After all, that is its purpose, right? As a result, I've criticised some design decisions sharply without realising how my tone and message have influenced my team's work.

Trust is in the heart of code review and deeming that all code is faulty unless proved otherwise will significantly damage the spirit of your team.

Instead of scrutiny, we should use code review for mentoring. Instead of telling what all is wrong in the code, we should guide people to improve. Fix the defects together and allow the mutual trust to grow. Soon the same developers have a tremendous amount of self-confidence, and implicitly they contribute to a better and healthier codebase.

Trust the Infinitely Improvable Code

Similarly, as an avid gatekeeper, it took me a lot of time to understand that the code written by others is not inherently faulty. The code might not meet my expectations of good design, but that's rarely an issue. All the code is infinitely improvable, and our responsibility as developers is to improve it.

As arguments arise in code reviews, it's important to practice humility and not push your solution too firmly. By saying that, do I mean that code review doesn't matter? No, but it's to be used wisely. Likely, the code reviewed to be acceptable now wouldn't pass the same inspection in six months.

Keeping the code easy to change allows us to refactor it to better serve our purpose long after writing. There's no need to expect perfect software to emerge during a code review when we can perpetually grow it. That is what makes software soft.

Photo by Alvaro Reyes on Unsplash.

When to Pair Program and When to Go Solo

Niko Heikkilä — Mon, 24 May 2021 14:58:16 +0000

Despite all the praise pair programming gets, it is not a silver bullet and we should carefully practise it to get the most benefit from it.

I recently finished reading Practical Remote Pair Programming by Adrian Bolboacă. In the description, the author promises to teach you the structure, organisation, communication, and tools for making (remote) pair programming successful in your (distributed) team.

Pair programming is complicated. Despite that, I've been practising and advocating it for a while, trying to build solid habits around it. Thus, the book naturally caught my eye. Besides, today most of the programming work is remote, making the book a timely publication.

In addition to describing when and how pair programming works to speed up your delivery process, it is crucial to understand situations where it might only slow you down. In this post, I will go over these situations briefly. However, I warmly recommend reading the book as well for complete insights.

Disclaimer: I will use the term pairing a lot in this post in place of pair programming. Many pairing techniques also apply to mobbing (mob programming), which means working in groups of three or more people. For beginners, I recommend starting in pairs and moving on to mobs after a while. In some texts, you might also stumble upon the term ensemble programming, a friendlier name for mobbing. After all, we are not here to smack down the code like an angry mob, even though programming can be frustrating at times.

The (Not-)Obvious Benefits of Pairing

Trying to convince your team to take on pairing can be even more challenging than programming in pairs itself. In this section, I will tell how and why pairing can make us better developers.

Pairing Is Mentoring

When I began to build software for a living, I was introduced to new projects, their conventions and other ways of working through pairing. I'm eternally grateful to all my colleagues who have paired with me.

The pairing has allowed me to grow orders of magnitude faster than being thrown to survive in a project alone because pairing is a pure form of mentoring. After a while, I too began pairing with new hires passing forth all the knowledge I had gained.

As in martial arts, those with a higher rank are responsible for teaching others with a lower rank. Pairing is all about this. Therefore, the best pairs are often junior-senior pairs. The junior is ideally a new hire or otherwise unknown to the codebase or domain. Pairing with someone on your level can work, too, although it involves less mentoring and growing.

The next time your team gets a new member, do not only throw entry-level tasks at them — pair with them, instead.

Pairing Is a Learning Tool

Like many others, I started my career studying computer science in study groups. The fundamental programming classes I attended always involved exercises. Often we would solve the given problems together, sitting next to the same computer sharing the same keyboard.

In the book, the author references the four levels of knowledge related to a concept known as staff liquidity. These describe the skills you possess about the current system or parts of it. They are as follows.

"I know nothing!" (beginner)
"I can run it" (intermediate)
"I can tweak and fix bugs" (advanced)
"I own it!" (master)

Although you typically climb these levels independently with occasional support from your team, the journey towards mastery is fastest travelled by pairing. When you pair to learn, you will develop a solid understanding of the system, enabling you to redesign or refactor it faster and safer than working alone.

The next time you need to learn a complex system or domain to manage it, pair with the one who knows it best.

Pairing Is Sharing Knowledge

The more we work alone, the more we gather silent knowledge about the inner workings of our code. It's inefficient and time-consuming to share knowledge only through documentation despite its importance for product longevity. We can conveniently build shared conventions about developing the product through pairing without having to sit in meetings or glance at massive pull requests.

A well-established technique is to form pairs from people working with different parts of the system. For example, a back-end developer should pair with the front-end developer working with requests to the back-end interfaces. Successfully applying pairing techniques will tear down the invisible walls in your team.

Note, however, that the shared knowledge should also be written down. Otherwise, it is only silent knowledge in your and your pair's heads.

Pairing Is a Social Event

Developers come in all sorts of flavours. Some like to do focus work being buried under music from noise-cancelling headphones. In contrast, others enjoy the company of their peers and have a chance to brainstorm complex problems together.

I belong to the latter group. In fact, I often feel more stressed and anxious when working alone. These feelings have also begun to intensify during the pandemic. Being isolated in continuous long stretches has made my performance significantly weaker. Thus, I need social programming to live and thrive.

Pairing and mobbing (style of pairing with three or more people) can also happen in social events organised within a community. Hackathons are a prominent example. If the employees are suffering from isolation, organising a community event is a beautiful way to build up the spirit and see new innovations grow.

In the book, there is a fascinating anecdote about the social aspect of pairing:

"During a community event that I was facilitating, while the programmers were pairing, a CEO appeared. He heard about this event and he was curious what was going on. Nobody had any idea about his role, and he joined, paired, and discussed just like any other attendee. Only after the event did I find out that he wasn't really a programmer."

Pairing is not only for developers. You can pair with designers, testers, product owners, managers and even your CEO under some circumstances. What value does your solution have if you can't explain it to your CEO, anyway?

Common Mistakes Made While Pairing

By now, you most likely noticed that you have tried pairing at least once, whether it was during your studies or junior years.

The unfortunate fact is that many of us stop pairing at some point. We might blame bad prior experiences or incompetent managers who think that features are done fastest when everyone is working independently.

It cannot be denied that pairing does not mean eating cake and drinking champagne from golden carafes all day. Hence, avoid these common mistakes.

You Should Be Pairing All Day

Pairing all day every day can make you exhausted and emotionally zapped at the end of the day. I can usually last no longer than two hours talking and writing code at the same time. Then I need to rest for at least 15 minutes to ease the fatigue. Continuously keeping up a pace like this will more than likely grind our wellbeing and drop our interest in pairing.

Doing the devil's math shows that we can split the average day of eight hours to a maximum of three to four extended sessions with short breaks in between. On paper, this sounds efficient, but it quickly proves as wasteful as any approach where developers are fully utilised. Remember, 100 % utilisation is a parking lot – or an express lane to sick leave.

It's better to start by pairing for 25-30 minutes straight (in total 1-2 hours daily), pausing briefly, and rotating roles before carrying on. If the task is finished, you can rotate pairs before starting a new task. I recommend you download a Pomodoro application or use any suitable timer to keep track of time. Rotating often keeps the spirit up as you are not stuck working with the same partner repeatedly.

Efficiently managing the time spent in the pairing will eventually make you less and less tired while you get used to this new way of working. From there on, you can increase the amount of pairing slowly. I have found out that I can roughly keep on pairing 75 % of the day. The rest 25 % I reserve for a slack time where I learn, research, or work independently. Your perfect percentage may vary, but don't let it creep towards 100 %.

Pairing in Hostile or Unknown Waters

While pairing, we need to bounce ideas back and forth when trying to develop optimal solutions. Inevitably some of our clever ideas can sound utterly crazy or prove ineffective right after saying them.

Therefore, pairing requires a psychologically safe space where you are not laughed at no matter what you say. Without psychological safety, you cannot bring forth your best ideas. In the worst case, you might end up silently following what others say, effectively reducing the pair to a solo effort.

If there are any tensions within your team, you should resolve those first before starting to pair. Suppose no one in the group knows the other person, as is sometimes the case in fast-paced consultancy projects. In that case, you should wait until the team has passed its forming phase and is comfortable working as a unit.

If the whole development organisation is on fire and people hate working with each other, then... well, just hand over your resignation.

Expecting a Formal Code Review After Pairing

Some developers accustomed to the ways of working in highly bureaucratic, process-oriented, and hierarchical cultures adamantly state that pairing is no substitute for a formal code review. It is further reasoned by saying that a third person with fresh eyes is supposed to catch all the mistakes you and your pair have made.

In these situations, ask how the third developer — who has no context or deep understanding of the problem at hand — could review the solution any better? Asynchronous ways of working have instilled the notion that we must always invite an outsider to scan our code. Contrary, the code review is most useful coming from peers who understand the context and problem. They are your pairs.

Suppose we have a process demanding an external code review despite pairing. In the worst case, you first have to wait for the third developer to detach from their current task. Then they suffer through all the negative impacts of context switching before studying the code you have written. Finally, they present you their often flawed feedback before switching back to their previous task again. This drastically reduces the team's throughput and increases your lead times.

Instead, try pairing in a continuous delivery mindset. Design, implement, review, test, and finally deploy your solution. Then make a (virtual) high-five, grab coffees, and move on to the next task. I've efficiently completed user stories with tens of subtasks without creating significant defects in a day or two doing so.

Pairing With Unclear Requirements

When your team has no clear understanding of the problem or the domain, pairing is not fruitful. You will likely end up staring at a task description — often phrased verbatim by the client or product owner — with open mouths for a couple of minutes before moving on to an easier task.

Fortunately, pairing is not always about programming because solving problems is not always about writing code either. You can pair with your product owner or team lead and together write high-quality requirements.

Pairing with Bad Coding Practices

Pairing is ineffective when tight schedules force your team to cut corners daily, resulting in technical debt. After deciding to improve the codebase quality, you can slowly start slicing through the legacy cruft and refactor the code in pairs.

Practical Tips Before Starting Pairing

This section shall briefly describe small tricks that have helped me whether pairing remotely or in the office.

Use Ensemble Commits

During pairing, we usually share the same codebase, which means that version control tools cannot accurately determine who has done what. It is not always crucial to attribute commits to specific authors. After all, the team should have collective ownership of the solution. However, it is a good practice to give credit where it is due.

This can be done with a technique called ensemble commits, in which you simply write the name and email of your pair in the commit message footer. See the example below.

feat(api): add a new route '/films' for fetching IMDb data

// optional longer description here

Co-authored-by: Steve McQueen <kingofcool@gmail.com>

Not all source control providers display this information correctly. However, GitHub favours this approach when specifying multiple authors. It is a great way to give credit to your pair. It also helps other developers to see who should they ask about this commit later.

Assign Roles

Besides writing informative commit messages, make sure to commit early and often. You can also assign roles — minding the rotation — while pairing. Test-driven development while pairing is particularly effective when the other developer is unfamiliar with solid testing practices.

In TDD pairs, the other developer writes a failing test. The other developer follows by writing the code to make the test pass. After a passing test, save the game by committing and proceed to refactor the solution. After the code is clean enough and the test is still passing, commit again. Eventually, you may squash the commits together if needed before pushing.

Use a Proper IDE

This is a matter of taste, but for myself, tools like JetBrains' Code With Me and Microsoft's Visual Studio Live Share are among the best pairing tools. You can also share a terminal session through a multiplexer like tmux. Still, I would avoid this unless my pair is perfectly comfortable swimming in the terminal and using a terminal editor like Emacs or Vim.

I have found Visual Studio Live Share the best tool for my pairing sessions. Most of the time, I share my local environment through the remote port forwarding feature. Doing so allows my pair to navigate to the same http://localhost:<port> address and see the live development environment. I can also share access to my terminal when pairing, which helps them to see what commands I use in my development flow. All this is done with few clicks, and it makes remote pairing almost as frictionless as sitting together.

While IDEs are geared towards remote pairing, they also work locally, given an ideal network setup and low latencies. For many, it's uncomfortable to share a keyboard (feel the germs! 🦠). Sharing an environment between two or more laptops is the better option.

Share the Screen for Context

Nevertheless, do not rely solely on your IDE because sometimes you need to show your pair the precise situation. Especially when working on front-end tasks, make sure you're sharing the right browser tab so your team can see what is happening.

Platforms we typically use for remote meetings like Google Meet, Zoom, and Microsoft Teams are viable choices.

Invest in the Equipment

Make sure you have a decent webcam, headphones and microphone available when pairing.

Never, ever use your laptop's built-in microphone and speakers. The sound of your typing and the echo of your pairs voice will severely distract their thoughts and abruptly thrash the experience. The book walks an extra mile describing different high-end podcasting setups with proper mic stands and pop filters. Still, you can make do with affordable headsets as long as they are not the cheapest earbuds. A good rule of thumb for headphones is to try them out while pairing for an hour. If your ears hurt, change the headphones.

You don't always need to have your webcam on. Sometimes it can make pairing feel more personal, but not everyone is comfortable with having cameras on all the time. Discuss this with your pair if needed before your first session. If you choose to have your webcam on, adjust the lighting so you don't end up looking like a black silhouette in front of bright daylight. Shut down any backlight sources and turn on a front light – not too bright – to make your face more visible.

Ensure a Stable Network Connection

Sloppy connection causes your voice to stutter or become robotic, which is a distraction. However, you don't need 1 GB optic fibre for pairing. As long as you make sure the connection is stable, latencies are low, and there's enough extra bandwidth for audio and video. The rest of the family should not be watching too much Netflix in the other room.

If you're using Wi-Fi, move as close to the router as comfortable. Plugin the Ethernet cable whenever you can. If the current task does not require using a VPN connection or other proxies, disable them.

Should I Pair?

In this post, I outlined many benefits, pitfalls and practical tips to ease your journey into pairing. However, the critical question is: when should I pair?

It is not always easy to decide. In my experience, there are specific tasks that are often better solo. These include but are not limited to:

deploying builds and running scripts
documenting existing features and writing simple instructions
checking if a reported bug can be reproduced
doing mundane and routine tasks, which should be automated, anyway

For all other tasks that require levelling knowledge, learning new concepts, or solving challenging problems, the answer is often yes. You should always be ready to pair.

If you need more help to get started with pairing, read the book. You can also contact me for coaching. Let us make the development world better by working together.

Photo by Nathan Dumlao on Unsplash.

You Can't Grow Yourself Unless You Grow Others

Niko Heikkilä — Sat, 01 May 2021 08:24:11 +0000

During our careers, almost everyone has regular one-on-one meetings, sometimes referred to as performance reviews. There we take time to go through our past, present, and future in the context of our jobs. In Futurice, these are called MyRetros, where my supervisor and I specifically look back on the last six months, the current state, and possible future endeavours.

Often it's not enough to have a minimum of two one-on-ones per year. Given that our supervisors may have many people under their supervision, it's essential that we also grow each other in a peer-to-peer fashion.

I'm happy to have been mentored by several experienced developers during my career. Still, I'm even more delighted to take that knowledge and pass it on to my mentees. Too often, we might think that advancing in our careers requires supreme technical understanding gained only through decades of hard work. Equally important is our set of soft skills and our capability to grow others.

We should set clear expectations during our performance reviews to not be promoted unless we have grown others. Our careers should have more meaning than plainly satisfying our egos and boosting our monthly salaries.

In the last couple of years, I've been actively transforming myself from a regular software developer to a mentor developer. It is challenging, but doing so keeps the spark lit, giving me a direction to progress.

In this post, I explain how you can transform yourself too.

The Several Benefits of Mentoring

Mentoring can sometimes be seen as a very formal relationship where you have to be a genuine senior staff member before mentoring juniors.

What is often missing from the picture is that we can also mentor each other irrelevant of our current titles. Everyone who has been a part of multiple teams knows what techniques have worked in particular contexts and can carry that wisdom to future projects.

You Learn Through Mentoring

A crucial aspect of mentoring is to understand that it is not unidirectional teaching and preaching. As mentors, we must learn and improve based on the feedback we receive from our mentees. I find the traditional division of junior and senior employees holding us back, especially in mentoring.

I've worked with seniors who have struggled with fundamentals and worked with juniors who have expanded my thinking with much more efficient solutions. In a sense, we are all juniors, but let's call ourselves people for the sake of equality.

Like our business models should not be strictly about business-to-consumer or business-to-business, our learning should not be from seniors to juniors, but peer-to-peer.

You Can Level Team Competencies

When you practice mentoring as part of your daily team routine, you end up levelling your team's competency. As a result, wide knowledge gaps occur more rarely, which is facilitated by continuous knowledge sharing.

Your design-oriented frontend developer should be able to help with databases and securing backends. Respectively, the developer handling DevOps tasks should be able to help with sketching new user interfaces. Everyone in the team should be comfortable talking to the client, bringing forth new ideas and challenging the old ways of working.

Furthermore, levelling the team helps to reduce the bus factor. The project doesn't halt when the integration specialist gets sick or when the business director burns out and is set aside for a couple of months. Thus, we need to build a team of solid generalists – also known as T-shaped professionals.

The desired side-effect of levelling the competencies is increased autonomy. When people are comfortable working in a generalist mindset, they feel a greater sense of freedom regarding what tasks they can pick. As I mentioned in my earlier blog post, autonomy leads to mastery which leads to finding our purpose. The three elements together significantly boost the retention and desire to work in your company.

You Contribute to a Better Hiring and Onboarding Experiences

Mentoring begins from the very first moment I meet someone. Interviews are a great place to practice mentoring.

If a developer is applying to your company either for a full-time position or a summer gig, I can mentor them. How could they improve their cover letter or resume? Did we give them a homework assignment? How could they improve their solution? As a bare minimum, I must give them a thorough code review in return.

When the new employee is hired, I can become a mentor for them. In Futurice, we have the concept of FutuBuddies, and we are the first ones who welcome the new employees into the house on their first day. From there on, we can agree to meet daily or weekly for a catch-up session which is naturally mentoring.

How Do We Mentor?

Being a good mentor is a lifelong challenge to which there are no simple answers. We can, however, define techniques every good mentor should possess in their belt. Below are six strategies I've learned to be effective.

Don't Shoot Down, Encourage

Let's imagine a situation where a new developer approaches me with the idea of rewriting a codebase with another language. Say, for example, they want to switch from Python to Golang or from Java to Kotlin.

Chances are they have been only thinking it through themselves without proper feedback, and the cost of unnecessary codebase rewrite might be high. As a mentor, I don't shoot down unprepared initiatives. Instead, I encourage them to think more. What if the developer would organise a workshop on the said language? How could this developer mentor the rest of the team to solve domain problems using the new language more efficiently?

I have always enjoyed recognising the process bottlenecks in my vicinity and trying to optimise them. Unfortunately, some of my ideas have been shot and even ridiculed in public channels in the far past. People have stated that it couldn't possibly work the way I have imagined. While the others might have had a grain of truth in their words, their approach was not encouraging.

Luckily, I was born with a strong head and resilience (what in Finland we call sisu), so the mental damage has been minimal. However, for others, aggressive approaches might even end up terminating promising careers.

As a mentor, I must always keep in mind reciprocity from social psychology.

"As a social construct, reciprocity means that in response to friendly actions, people are frequently much nicer and much more cooperative than predicted by the self-interest model; conversely, in response to hostile actions they are frequently much more nasty and even brutal."

Wonder why that co-worker has been ignoring you or acting offensively? It might be what you did to them in the past.

Don't Feed Them with a Spoon, Challenge

Sometimes mentees approach with simple questions. Instead of doing their homework and spoon-feeding answers, mentors ask follow-up questions.

Where is the documentation located? Where have you looked? Who have you asked?
How can I make my code cleaner? Do you see any repeating patterns that could be abstracted to a shared function or library?
Niko is writing crappy code, and it's killing me! What are you going to do about it? How can I help to solve this problem without firing Niko?

Don't Reserve, Delegate

As you level up in your career, one of the most rewarding sensations is your increased ability to take on new challenges without feeling like an impostor. The more difficult task at hand, the more confident you are in your ability to tackle it faster and better than others.

It's not a surprise that mentors do not act like this. Instead of reserving the juiciest tasks to themselves and letting the team do mundane stuff, they delegate. Successful leaders take pride in watching their team complete challenging tasks while staying in the background and occasionally offering help. An approach like this requires rigour, but in the end, you have made your team an unstoppable value delivery machine.

It's also important to delegate responsibilities. Don't be the only one talking to the client. Let Alex book, prepare and handle the next demo. Let Emma guide the next sprint retro the way they feel would be necessary right now.

Don't Hold, Share

Many discussions between mentors and mentees follow the pattern of mentees explaining their situation and mentors asking questions. What's crucial and may often be missed is for mentors to share their experience as well.

Does your mentee have a difficult time focusing on work due to a personal life crisis? Try to share some of your experiences and how you overcame them – without belittling their experiences. While interviewing a candidate, make the event more relaxed by sharing how anxious you too were in one of your first interviews. Sharing is caring.

Set the Rules

We all work under specific rules. Particular rules like reporting our hours for invoicing or delivering work on time are self-explanatory. There are also many invisible rules – conventions – which could help your team further.

For version control, small atomic commits and conventional commit messages ensure the codebase history is linear and easier to follow. For quality, test-driven development rules us to write only so much code that our tests pass. For faster delivery, continuous integration rules us to push our work into a shared main branch daily.

As mentors, we set clear rules on how the team works effectively.

Do Together

Finally, the shiniest gem of them all is co-creation patterns. It makes me sad to see how many developers like to work things independently, even in the office. Outdated management views further incentivise solo work. Some managers think that people working on many simultaneous tasks is somehow more effective.

In truth, we should voraciously swarm to solve problems. We are already doing this early on in the design phase when we co-create with tools like Google Docs, Sketch, and Miro. When it comes to coding, we tend to split tasks as far as possible and let people pick their favourites to work.

As mentors, we understand that our team is a cohesive unit and not a random bunch of individuals. Lead by example. Always be ready to pair with different people in your team. Experiment and gather feedback regarding what worked and who enjoyed it. Rotate pairs and iterate.

Building Relationships Through Mentoring

Mentoring is an effective way of getting to know our co-workers. To give meaningful feedback and advice, we should have established a relationship with the other person. Do we know what our mentees are interested in and what goals they have for their career?

As a mentor, I can inspire these interests and goals myself. Suppose I'm practising clean code and extreme programming principles in a team and continuously showing how I build quality while delivering remarkable results on time. In that case, others will surely follow me with interest and attempt to learn. They can be set off to a great path of software craftsmanship.

Naturally, as human beings, everything we speak of doesn't have to be professional. After a weekend, I can mind the team member who had to take their cat to a vet on Friday. How is the cat doing now? Continuously showing interest in people's lives helps gain trust and respect, which goes a long way in helping you work better as a team.

Traits of a Great Mentor

Finally, here is a non-exhaustive list of traits that matter when developing yourself as a mentor.

Knowledge. What experience and skills do you possess. How extensive is your professional background?
Authority. Who are you? Why should people listen to you? Do other people know what you have achieved?
Confidence. How confidently can you express your ideas and solutions?
Charisma. What kind of body language do you use? How does your voice sound?
Emotional Intelligence. How easy it is for people to trust you. How well can you empathise with others? How deeply can you collaborate?
Team reputation. How successful your team and its members are in the eyes of the organisation and client?
Thought leadership. Are you a recognised blogger or speaker? Are people lining up to work with you?

Keep calm and carry on mentoring!

This is the second post about observations I gained from The Principal Developer workshop. Read also my earlier post on reducing the work-in-progress and increasing throughput following Little's Law.

Photo by John Schnobrich on Unsplash.

How Spice Program supported my creation of 235

Juha-Matti Santala — Mon, 19 Apr 2021 12:43:15 +0000

At the end of 2020, I decided to finally start learning Rust. For over a year before that, I had been playing with the idea of it but it took me all the way until the end of 2020 to get started. Rust is an interesting language for me, as I have mostly programmed with languages like Python and Javascript. Rust is something quite different and from the outside looking in, its community looked great as well.

After my initial steps with the language where I was solving Advent of Code puzzles, I decided to build my first software with Rust. I'm an active command-line user so for me the obvious first choice was building a CLI tool. Hence, on a dark wintery Friday evening, I started working on a hobby project that would become 235.

What's 235?

For the small subset of readers who live in Finland and have been fans of the National Hockey League (NHL) for a long time, the number 235 rings a bell. For decades, the Finnish broadcasting company Yle has provided NHL results on their teletext service on the page 235. For me, and many others like me, it's a habit to start every day by checking the page 235 to see the results of previous night's games.

Inspired by this cultural phenomenon, I decided to build a tool that combined the minimalist and iconic style of that teletext page with data from an API for NHL results.

235 is my first Rust program and it provided me a great opportunity to learn a new language – the spec was small and well-defined - it didn't require complex advanced features of the language - I knew it would be useful for me and people like me on a daily basis.

For learning & hobby projects, that combination of usability, simplicity and small scope is key. I know I'm not the only one with dozens of unfinished projects that grew too big from the original idea and with limited time to work on, personal projects never ended up being finished.

235 is published with MIT license and the code can be found on GitHub. (The project is called nhl-235 because Rust doesn't allow project names to start with a digit.)

Distributing executables is a very different world than web apps in browsers

As I mentioned above, this is my first Rust project and coming from a background of really different languages, there has been a lot to learn. This is the first time I've been working with binary executables. For almost two decades, I've loved web for its distribution model — you write code, deploy to server and it's updated for everyone. With executables, people need to proactively update their versions which means I need to think about new ways to reach them and communicate.

Certain things are also much slower for me to develop. One thing I really enjoy with Python and Javascript (both given their dynamic style and my experience writing them) is how I can focus much more into the content and domain, and much less on meta level things. I recently shared my thoughts about Option and Result types on my blog. Even though I have a theoretical understanding of how they work and what their benefits are, my development too often comes to a halt and I need to rethink and refactor things a lot more with Rust.

Luckily, the Rust community is great and I've gotten so much help in my learning journey from local and global Rust developers who have been so helpful and compassionate when I've been stumbling around trying to understand the basics of the language and how to write it.

And my employer supports my work on 235

In 2013, Spice Program was born as our open source and social impact program. Part of it is the support for open-source contributions of Futuriceans. In a nutshell: when you work at Futurice and do open source work on your own time, we support that with a monetary bonus of 15 euros/hour, capped at 30 hours/month.

In 2019, we expanded it to be more inclusive to people in the company who don't code:

The key purpose of our volunteering bonus is to make use of and develop your professional skills for social impact. For us, open source is always considered social impact, but there are many other ways to achieve that impact.

When a designer helps to create a beautiful web presence for a poor non-profit on an important mission, it should count, even if the graphical assets cannot be properly published as open source.

When an HR specialist helps in organising and running code schools for kids, it should count, even if there are no digital deliverables.

When a business advisory professional teaches principles of lean service creation to an NGO striving to make sure whales don't start smoking, it should count.

From a perspective of a developer, I'm happy that I get to build things that I want to see in the world and be appreciated for that with a small bonus.

And even more, it enables and incentivises me to learn more and to contribute to the open source ecosystem. With its flexibility, I'm not forced to do anything or have to make choices between other things in live and coding: sometimes I spend a weekend on a personal passion project and sometimes it's months that I don't code anything on my free-time.

One thing I realised only after I had built the first version of my 235: the API I decided to use was also developed with Spice support back in the day. That's the beauty of the open source ecosystem and community: things you build today can be fundamental in helping others build new things.

Over the past few months, we've been averaging at roughly 700 hours of Spice contributions per month. You can find more about the Spice Program here.

Reducing the Lead Times with Little's Law

Niko Heikkilä — Tue, 30 Mar 2021 18:18:10 +0000

There's a fascinating law of mathematical theory applicable to agile software development, which helps you deliver features faster without sacrificing quality. It's called Little's Law, and it dictates that the average lead time of delivery is the team's work in progress amount divided by its throughput.

First, let's define the terms.

Work in progress (WIP) is the number of backlog items the team is currently working on. These items are not yielding value for the customer. WIP can be determined by counting those cards in your project board that are not in the Backlog column and not in the Done column but somewhere in between.

Throughput is the measured amount of backlog items a team can complete in a fixed period, which is usually a day.

Example:

The team has 20 tasks in progress, and its average throughput is four cards/day. Following the law, this gives an average lead time of 20/4 = 5 days.

To foster an effective software development process, we should target our efforts towards shortening the lead time. Following the laws of mathematics, we can achieve this by limiting the WIP and increasing the throughput.

Often we fool ourselves to think that high WIP and high throughput are synonymous with performant processes, but this leads to stagnation, low motivation, low innovation, and burnouts.

In this post, I attempt to share approaches to doing it right, but your mileage may vary.

Reducing the Work in Progress

A golden rule of limiting the WIP is to stop starting and start finishing.

Total WIP should be smaller than the number of people in the team. If possible, strive for a WIP limit of one, but mind that it's not always a feasible choice.

When working under a strict WIP limit, you should leverage the daily stand-up with your team for prioritizing and selecting the tasks for today. If the WIP limit is reached, nobody is allowed to start new work. Instead, everybody should help finish the ongoing work – be it developing, reviewing, testing, or deploying a new feature.

Teams wanting to reduce WIP should focus as many people as possible on as few tasks as possible. Some people think this only applies to Kanban, but Scrum too has a specific technique for this: swarming.

Pair/mob programming is also a natural and effective enemy towards high WIP. Instead of distributing one task for each developer, make them solve the problem together. Pairing and mobbing are not only for programming, as you can also practice design, testing, monitoring, leadership, and many other tasks together.

Essentially, when people pile on a single task, they can design, develop, test, and deliver it more cost-efficiently. Mobbing has its limits, though, and we should find balance through careful studying. Too many people working on a single task invokes the law of diminishing returns and eventually hurts the performance.

Additionally, to make the mobbing work, all teams should be cross-functional, consisting of designers, developers, testers, and deployers with a well-balanced skill set. These teams deliver vertical slices.

Note that the latter two roles don't often require separate people because developers can test and deploy the changes themselves. In case you have an independent QA team, make sure to involve them early on in the process, tear down the walls, and enable deep collaboration.

Increasing the Throughput

There are three actions a company can do to increase its teams throughput.

Hire more people, but not too much (consider a two-pizza team 🍕🍕 the maximum size – leaving the exact number for you to decide).
Make the team more proficient by fostering Extreme Programming principles.
Eliminate patterns of waste (see below).

I consider XP principles and eliminating waste very effective actions here. Below are the most common forms of waste you may encounter in your development process.

1. Partially Done Work

We cancel or postpone tasks, our work is stuck in the testing queue, and essential features are waiting for deployment. Swarming and a low WIP limit ensures the team is focused on a fixed number of tasks at any given time. Remember, partially done work does not yield value.

2. Overproduction

We are often tempted to design non-trivial, abstract, and flexible code for the speculative future, which might never happen. We may add complex data analysis and charts functionality to the project instead of adding an Export as CSV button. Instead, think about how you can solve problems with less or no code.

We might drive ourselves into an endless loop during refactoring code where we polish secondary or unimportant code. Such code might not even change that often nor slow us down, so why bother with it?

Alternatively, we apply the best development principles while developing throw-away prototypes. Refactor only so much to keep the code maintainable and easy to understand until the next time it's changed.

We might deliver features with low or negative user impact. We should carefully observe and respond to UX metrics and customer feedback.

We adopt trendy technologies and tools, whereas the tools we already know how to use would suffice (see Marchitecture).

We chase 100% test coverage for our unit, integration, and acceptance test suites. Still, we ship design defects that are difficult to detect and recover from in case of disasters. Customer finding out a bug in production before your team does is a bad, bad thing.

Our product owners maintain huge backlogs with more user stories than needed for the next few sprints. YAGNI rule is the single best defence shielding us from this.

3. Waiting, Delays, and Handoffs

We are maintaining a slow and unstable regression test suite relying on external integrations. Running it keeps us waiting for results due to constant failures. Additionally, the build server is shared with other teams and maintained by a fantasy creature referred to as the DevOps Engineer. Why not use on-demand testing environments, or even better: run all the tests locally?

For the better part of the lead time, the code is waiting for someone to review it. Some features require review from a senior developer who is at the moment drinking mojitos in Bali. Align the team's skills so knowledge gaps can't happen.

Teammates are involved in multiple projects, and the same human resources are being shared across squads. Build long-lasting teams with domain expertise as a core objective.

Unexpected, critical, and non-trivial production incidents might pop up in the middle of other work delaying the feature work further. Good observability and XP principles protect us from this.

4. Rework

Pull requests are bounced back and forth between the author and reviewer in asynchronous code reviews. Use trunk-based development, pair programming, and a continuous integration mindset to avoid this.

We need to re-implement solutions due to misunderstood requirements or fix the same bugs twice. If the product owner can't define the requirements, go and talk to the customer yourself. Use behaviour-driven development to make sure work is only considered done when acceptance criteria are met.

Due to poor communication, we need to answer the same questions, or the lack of automation forces us to run mundane routines repeatedly. We should capture the necessary knowledge in software documentation and architectural decision records.

5. Non-value added activities

Long-lived feature branches force us to rebase continuously and deal with resulting merge conflicts. Stop branching and start integrating.

At the end of each sprint, we have a retrospective without action points and assigned responsibilities. Shake up the process and start setting action points.

Our calendars are filled with never-ending meetings and attempts to reach consensus without making progress (impasse). Apply Basecamp's internal communication strategies to heal this.

Summary

Little's law is one of the most powerful drivers in serious software development efforts because of its simplicity. You don't have to maintain complex models or calculations to observe your delivery performance – a fractional operation does it for you.

I gained the majority of these observations in reducing the WIP and eliminating waste during The Principal Developer workshop. Workshops like these provide invaluable tools altering the way you think about processes, teams, and cultures. I argue they offer a more significant return-on-investment in your career than simply learning frameworks and tools like React or Docker.

Photo by Daria Nepriakhina on Unsplash

How we co-created our technology strategy – and what we learned in the process

jushac — Wed, 24 Mar 2021 10:25:52 +0000

Building a strategy is always an involved process. This past fall, we took it upon ourselves to build a technology strategy for Futurice leading up to the year 2022. By structuring the work in a smart way, we were able to make it fairly easy on ourselves and complete it in less than three months. In addition to an actionable tech strategy, the process also yielded a ton of important lessons.

The primary focus of our strategy work was on the business landscape in Finland, but naturally many of the themes and trends around it are global. The main reason for building the strategy was to create clarity and focus, both for our people within the technology domain and others around it, like sales and HR, or HC as we like to call it – short for Human Care.

Additionally, with a technology strategy in place, we are better equipped to take a stand on what we want to do and what we don’t. It also gives us a handy tool to help guide our focus and efforts in the long term, and conversely, it will also be an instrument we can check retrospectively and see which bets we got right and which ones we didn’t. Having those insightful "Hey, we nailed that one" and "Yeah, didn't see that coming" moments.

In order for our tech strategy to do its job properly, we needed it to be an inspiring read for our technologists and touch their daily life at work. On the other hand, it would also have to be easy for our business people and other stakeholders to utilize in their work. Not exactly an easy task.

Our desired level of detail was set to be tangible enough to apply to everyday work, but not get all the way down to the nitty-gritty. We can expect to see lots of changes in tech over the next two years, so there’s little use trying to make guesses on an unnecessarily detailed level.

When creating our strategy, we wanted to get as much information from our tech community as possible. It was clear from the get-go that the strategy would be the culmination of our technological knowledge gathered from the community, and not just a handful of key people. All told, the process spanned little more than two calendar months and unfolded over the course of about 10 workshops of various sizes.

From the high level to the day-to-day

The strategy was designed to work on all levels from the bird’s-eye view all the way to more specific grassroots items with the level of technical details increasing when moving from the higher-level items to more detailed issues, like the use of TypeScript in frontend development. The transition from "fluffier" themes towards the hardcore technology landscape felt natural and gave our strategy more structure.

Figure 1: A gradual transition from high level items to technical details

First, we needed to align our technology strategy with our wider, company level strategy. We did this by binding our company level items to technological items on the country level to create a natural progression. At the same time, this also helped outline what kind of projects we take on, and with what kinds of teams. And so, the basis for the rest of our technology strategy was set.

Next up, we created a country level vision for our technology business. One can always argue whether this is necessary, but we felt that there was a need for a simple and concise statement that encapsulates what we stand for:

Inspire our clients to use technology in creative ways to solve complex problems for their customers, employees and society at large.

And building on the above statement, we also defined a set of principles that we see as overarching guidelines of how we want to run our technology practice. This step takes us closer towards concrete things. The roughly dozen items on that list contain statements like:

Our technology choices are guided by feasibility, maintainability, and business rationale. We enable people to evolve within the tech domain and outside of it.

Many of these are things that go without saying, but putting them in writing makes them more effective and something we can use for guidance when making decisions in the future.

Naturally, a strategy also requires us to have goals. These goals are something we should be able to reach with the right actions. They describe our desired state in market position, people development, partnerships and the kinds of projects we do. Since these are long-term items, they require incremental progression to reach them. This progression happens through concrete actions within all of our specialty areas – hence the next and most concrete part of the strategy, specialty areas.

Figure 2: Inputs to the strategy, its alignment outside the tech domain, and use after the process

Specialty areas

The various areas we cover technology-wise is massive, and basically extends from mobile to cloud infrastructure, and everything in-between. To make the work more manageable we ended up splitting it into these specialties:

Web development (frontend and backend)
Mobile development
Data science and data engineering
Cloud and architecture
Technology in the business context
Agile delivery
Partnerships
Tech community

Naturally, there is lots of overlap between all of these – for example, consider Firebase, which can land either on Cloud, Web development or Mobile development. When such issues came up, we simply made an educated judgement call. For the end result, it didn't really matter which side of the fence the items were on.

In that list of specialties, two areas – Partnerships and Tech community – stand out as slightly different from the rest, but both nonetheless involve analysis of our current state and include focus points for the next two years.

Each specialty needed to reflect on three main points:

What are we good at now and where do we have room for improvement?
What trends affect us globally and through our clients?
What should we focus on for the next two years?
Again, we wanted these topics to give us a nice flow. The first step would be to look at where we are now with a CSA-type of approach. We did this by analyzing our data on what kind of skills our people have and what we've been using in our projects. This gave us a good picture on where we are and where the market is at regarding the specialties. This yielded us insights like:

In front-end development, we have 195 people skilled with React and the most common choice in our projects is React with TypeScript. In web development, we are experts at building complex, high-performing and scalable web applications like the Sanoma News Platform.

We then started researching global trends, our clients’ future needs and our own views on where the world would be going. The goal here was to create a clear and focused outlook from the point of view of technology-enabled business. Naturally we tried not to embrace the whole world and instead stay focused on technology in our context. On the other hand, this also meant technology in almost all business verticals – which is not exactly a small focus... This gave us outputs like:

While in most cases APIs serve a specific purpose and it may not be necessary or even desirable to centralize everything, there is a clear trend towards a more structured API development strategy.

After compiling these two parts it was finally time to make choices on where to focus based on the background work done so far. This part also included choosing where not to focus.

The growing need from our clients to move their on-premises monoliths to serverless cloud environments also requires us to keep building our capabilities in that area.

The final result was a package that described what to do next as well as the background behind that decision.

How we organized the process

The building blocks that eventually made up the core insights within each specialty area, as well as the underlying trends, were generated by assigning people the responsibility to facilitate the process under each specialty area, and gather information from our technology community and other sources.

In practice, this meant looking into lots of data sources and workshopping with the relevant people. In the end, the results were distilled into a more condensed format, while all the material that went into them and was created during the process, like slides, documents, Miro boards etc. were of course stored for future reference. Once all the specialties were packaged, it was a question of doing a once-over and checking that everything was aligned, logical and made sense business-wise.

Figure 3: Involving people outside the core team benefits the knowledge gathering phase

Our approach was highly participatory, and it involved dozens and dozens of contributors from across the company. A big part of why we did it this way was to be inclusive throughout the process. Managing contributions from a large number of participants always runs the risk of devolving into a sprawling mess, but we were able to avoid this by introducing precisely the right amount of structure – not too rigid, but chaotic either.

Looking back, I feel that this was by far the leanest strategy process I have ever been involved with, but at the same time, we ended up with a very clear and usable document going forward. It will also be an important input for planning our future activities around recruitment, training and business.

What's next

In its plainest version, a strategy is just a document in a cloud folder. That is why the road that took us there was already important in and of itself, having involved multitude of technologists and business people. Right now, we are in the process of planning the actions based on the strategy, and agreeing on them with all the stakeholders within the company. To ensure the planned actions are executed, they will be a part of our quarterly OKRs on the country and/or team level.

To remain agile, we will have strategy reviews every six months. The changes in technology never stop, so we need to assess what we have been doing and adjust accordingly. Now that the strategy is already in place, adjustments are much easier to make.

As a byproduct of this work, we have spun off the Futurice Tech Trends 2021–2022 report from the strategy work, and made it into a standalone website and document that describe the driving technology trends affecting our business and that of our clients. Definitely an interesting read for anyone working in the technology industry.

Takeaways

Start with the “why”. Make it super clear why you are doing the strategy, and keep that as your north star. Know your audience. Know who you are trying to reach, and speak their language.
Involve technologists. Use your people to gain the best possible overall picture as well as their buy-in. A good technology strategy does not come from the heads of only a few senior experts. On the other hand – make sure to keep moving, lead the process, and avoid analysis paralysis.
Don’t forget the business. Technology is never an island. Every tech decision needs a business rationale, and you will also need the business buy-in. Furthermore, business has unique knowledge on client needs and the overall market situation.
Make it tangible. Company level strategies can be more high level and inspirational, but a tech strategy has to be something that people can relate to in their everyday work.
Relentless actions. Align your actions with the strategy, and relentlessly drive them forward. Otherwise the strategy will amount to nothing more than just another document on your cloud drive.
Establish follow-up. Schedule a review every six months and go through the strategy. What did we get right? What needs adjusting? After the foundation is there, fine tuning will be much easier.

If this raised any comments or questions, I'm happy to hear them in the comments section.

This post was originally published in the Futurice blog here --> Link

Blocking Time for Tasks with Toggl

Niko Heikkilä — Mon, 22 Mar 2021 07:05:39 +0000

For people doing mainly project work, planning daily tasks is a constant struggle, which can cause severe issues with productivity and mental well-being.

As a software developer with multiple projects on my daily schedule, I used to waddle in a sea of chaos. Attempting to swim and survive throughout my days impacted my work in many ways. The loss of context made it difficult to focus on tasks, which caused my productivity to halt and gave a diminishing sense of accomplishment in return.

Furthermore, when I needed to recall what I had been doing on a given day, I had to resort to checking my browsing history. As you might guess, it had little relevance to what I had worked. Daily standup meetings mainly were a burden where I was supposed to figure out what I did yesterday and what shall I do today. Similarly, the reported hours contained some time to this project and some time to that.

The technique of surviving with simple to-do lists — where Todoist is still the king — I had learned previously was suitable for single-project environments. There I could split my days between writing and reviewing code in one domain. It didn't scale at all for multiple sequential tasks. Fortunately, later on, I discovered the magnificent technique called time blocking, where every minute of the day is given a purpose.

Let me tell you how.

Basics of Time Blocking

Time blocking means saving time for important — not necessarily urgent — tasks in your calendar. With your chosen tool, start by dividing a day into slices and decide one and only one theme you're working on during a particular time block.

Don't worry. With time blocking, you get to keep your regular breaks and days off. This post is not one of those foolish blurbs hailing 60+ hour work weeks and waking up 4:30 every day to solve productivity issues.

After dividing your days into slices, your day might look a bit like in the picture below. Note that the themes are only examples, and I usually write those down precisely to help me later recall what I worked on.

How Do I Split the Day?

My typical day is as follows. Due to the dynamic nature of my profession, some variations may occur, but mostly it's easy to stick with the plan.

From Morning to Noon

I start working between 8–9 in the morning and sketch my time blocks for the day. Next, I begin responding to urgent stuff like emails and messages before clearing out the path for focusing on tasks. Then I grab a few planned tasks and complete them at my own pace.

After the first round of intensive focus, I attend a daily standup with my team. Here I leverage the time blocks from yesterday and today while explaining my status and possible blockers. If any meetings have been invited, they are usually held around mid-day.

Lunch Break / Time Off

With the first half of the day completed, I allow myself to take a decent amount of time off eating, drinking and relaxing. Together with the daily shutdown, it's one of the most important events of the day, and you shouldn't skip it.

From Noon to Afternoon

When I return to focus work, I then go over the pending code reviews or help team members debugging issues. This kind of work fits my afternoon mental state as most of the urgent stuff has already been done and now there's time to shine some creative light.

To call it a day, I begin slowing the pace down around 16–17 and make note of all the tasks I've achieved. Shutting down at regular times is essential for the mind to function correctly.

Toggl Track to the Rescue

I first tried using traditional paper and the Remarkable tablet for time blocking, but having my schedules tied to one device quickly drove me to use Toggl Track. It comes with excellent desktop, mobile, and web apps allowing me to access and edit my schedule from virtually anywhere. I don't use Toggl's flagship timer feature that much. The very intention of time blocking is to plan and control my time spent instead of spontaneous tracking.

Toggl web app has a nifty calendar view which is ideal for drawing blocks of time with a mouse and marking them to specific projects. You can also extend it with your calendar. I've hooked my Google work calendar into it, which allows me to duplicate each calendar event as a time block. Fun fact: when you're involved in a project with all-day meetings the time-blocking is automatically there, but it will hurt you in other ways.

Why Command-Line? Why Not?

nikoheikkila / hours

A command-line companion for the Toggl Track software. Check the README for supported features.

⏰ Hours

Working as a consultant requires you to mark your billed project hours periodically for invoicing. This is boring but luckily Toggl is there to help. Unfortunately, not everyone is using it directly.

Hours is a command-line tool built with Go for integrating to Toggl Track. Currently, it supports the following features:

listing saved time entries in various formats

Upcoming and planned features are:

creating new time entries
deleting saved time entries
starting and stopping the timer on certain tasks

Documentation

Documentation is divided into the following sections.

View on GitHub

However, one thing I was missing from Toggl was a performant terminal app. So, as a hobby project and because my current employer sponsors the personal time spent in open-source, I started writing one. Enter Hours. It's a lightweight, single-binary, open-source terminal companion for Toggl written in Go. At the moment, Hours ships the following features:

listing the saved time entries in various formats using the public Toggl API
styling the plain text output with termenv
converting the output to Markdown, JSON, and CSV allowing you to post-process data with other scripts

Fortunately, the Toggl API is convenient to work with and I've been delighted how easy it is to marshal Go structures to JSON and vice versa. Thus, more features are definitely on the roadmap. I'm thinking of implementing features such as starting and stopping timers without forgetting the basic time entry CRUD operations (create, read, update, and delete). Since Hours is still in the very early stages of development, you can help me improve it!

Conclusion

Blocking time ensures I can complete essential tasks while still reacting to urgent tasks. Having a clear daily plan helps me to recall individual days back to mind. I can also enjoy the rewarding sensation of accomplishing tasks. Most importantly, it helps me to stay away from unnecessary distractions. By the way, I don't have any desktop or web notifications enabled while working, so deal with it. Naturally, time blocking can't eliminate all the stress that a busy world with many projects brings forth, but it guarantees continuous calmness throughout the day.

Throw me with a message if you need help organizing your day with time blocking.

Photo by Aron Visuals on Unsplash

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.

How I handle my notes with symbolic links

John Cheng — Sun, 21 Feb 2021 17:37:14 +0000

Background

Handling notes has always been tricky for me. Should I use an app or have markdowns in a folder?

Lately, I decided to only use markdowns and have them centralised in a folder called notes while making them accessible in the relevant projects via symbolic links.

Objectives:

Access only project specific notes in VSCode (or any IDE)
Keep a folder containing all of my notes

How-To

Architecture

~
|-- .gitignore_global
|-- Documents/
    |-- notes/
        |-- project_foo/
    |-- project_foo/
        |-- .notes/ (ignore from version control)

Instructions

The first step is to have the version control ignore the notes in each projects. For example, I decided to have my notes in a .notes folder under each project.

# Create a global gitignore
touch ~/.gitignore_global

# Add the folder that will contain the notes in each project
echo .notes >> ~/.gitignore_global

# Add the global gitignore to the git configurations
git config --global core.excludesfile ~/.gitignore_global

Now, let's create the folder that will contain all the notes:

# Create the folder where all the notes will be centralised
mkdir ~/Documents/notes

Finally, let's say we have a project called project_foo. We can now create the folder that will contain the notes and link it:

# Create the folder where the project specific notes will be found
mkdir ~/Documents/notes/project_foo

# Link the project specific notes folder into the project
ln -s ~/Documents/notes/project_foo ~/Documents/project_foo/.notes

Summary

Folder notes contains all the notes
Each project has a .notes folder with only related notes and ignored by version control
All the notes are synced between the notes folder and the .notes one in each project

Thanks to this architecture, I am now able to access my project's notes in my IDE directly and avoid using another app for that. To add to that, because they are synced in the notes folder, I still have the possibility to open all my notes at once if needed.

Final words

Thank you for reading my first ever blog post and I hope it helps some of you :)

Let me know your thoughts and/or improvements!

Photo by David Travis

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.

Becoming a Certified Web Accessibility Specialist

Eevis — Sun, 17 Jan 2021 14:16:54 +0000

My second measurable goal in web accessibility for 2020 was to pass the Web Accessibility Specialist-exam. I thought that I would receive the results in 2021. However, I got a Christmas surprise. The message congratulating me on passing the exam was in my inbox on Christmas Day. If you want to read how I felt pretty soon after getting the results, I wrote a blog post about that:

I Am Certified Professional in Web Accessibility! 🎉

Eevis ・ Dec 26 '20

#a11y #certification #html #webdev

This post is a similar wrap-up-post from the WAS-exam, as I did from the CPACC (Certified Professional in Accessibility Core Competencies)-exam.

What is WAS?

International Association of Accessibility Professionals (the organization providing the certification) describes WAS with the following words:

The Technical-level credential is intended for accessibility professionals who are expected to evaluate the accessibility of existing content or objects according to published technical standards and guidelines, and provide detailed remediation recommendations.

IAAP WAS Certification

It is a more technical certification, which requires more understanding of how to build web that is more accessible. It doesn't necessarily require much coding experience, but some HTML, CSS, and JavaScript knowledge is needed.

Learnings

Again, as with CPACC, I can say that I learned a lot. I used Deque's WAS-package for learning, and I liked it. It contains lots of different courses and took a long time to go through, but it was worth the time. Also, I used the WAS BOK (Body of Knowledge) as a guide for studying.

WAS, too, consists of three parts:

Creating Accessible Web Solutions
Identify Accessibility Issues in Web Solutions
Remediating Issues in Web Solutions

I'll go through each category, picking up some points from each. They're all broad themes, and I can barely scratch the surface on this post, but hopefully, you'll get something out of my notes!

Creating Accessible Web Solutions

In the first section, the first topic is all the relevant guidelines and techniques for meeting the success criteria. These mean, for example:

WCAG 2.1 (Web Content Accessibility Guidelines)
WAI-ARIA (the Accessible Rich Internet Applications Suite)
ATAG (Authoring Tools Accessibility Guidelines)

Before studying for WAS, I had some idea about each of them - more about some and less about others. For example, WCAG was somewhat familiar to me, and I knew what it was, but this was the first time I actually read the whole set of guidelines. It was refreshing and educational.

Another thing in this section was "Basic knowledge of programming" - I thought I knew a lot about programming accessible interfaces, but oh boy, was I wrong. I learned a lot about semantic HTML and different techniques for creating a more accessible web. Also, I got to know about WAI-ARIA Authoring Practices and Design Patterns, which has been a valuable source of information when creating custom widgets.

Before studying, I had only a vague idea, how assistive technology can affect websites. For example, when a user uses a screen reader on mobile, it disables all the website's custom gestures. It means that if something is based purely on, for example, swiping content and there is no alternative way to access it, a user can't use that feature or app.

Another interesting bit of information I acquired from the studying process was how people using assistive tech use the web. For example, navigation with a screen reader happens differently from how a person who sees, navigates through the web page.

I have to admit that I came across many things that made me realize how ignorant I've been when coding (and still often am, as I am still learning every day). I've created so many inaccessible interfaces, and this feeling of being ashamed pushes me towards reading more.

Identify Accessibility Issues in Web Solutions

This section was an interesting one, and the focus is on finding the accessibility issues from the websites and identifying the relevant guidelines and principles regarding these issues. A big part of this section was the testing methods - be it automatic or manual testing. I'll write some words about the latter.

Manual Testing

I took a deep dive into different screen readers. I even turned my old Windows computer on for some JAWS testing. However, I never got there because, well, all the Windows updates took a remarkably long time, and in the end, I didn't have enough space on the computer. 😅

I've used VoiceOver on Mac before but going through the material taught me more about the keyboard shortcuts in VoiceOver. I still have to check the shortcuts almost every time I'm testing something with VoiceOver, but I'm getting better! I also learned the basic gestures for Android Talkback and tried VoiceOver on iOS.

I am adding a comment here before proceeding. I am a sighted person and can't be an expert on how actual screen reader users use the program. However, learning to use a screen reader helps with testing and understanding what needs to be taken into account for screen reader users. Anyway, this should not be the only testing made to an app with screen readers. In the perfect world, actual screen reader users would be included as testers in the quality assurance process.

One other thing I want to point out: Often when talking about assistive technology on the web, the first (and sometimes only) thing that people think of is the screen readers. That's not the case - for example, Windows High Contrast Mode, ZoomText and MAGic (for screen magnification), and keyboard-emulating assistive technology are widely used, to name a few.

Testing with Keyboard

And yes, the keyboard is on the list too. It is maybe the most straightforward testing you can do for a website - in most cases, you already have all the equipment and can start testing. Can you navigate the website without a mouse? Is everything usable? Do you know where the focus currently is? If you open a modal, can you access elements behind it while it's open? Where does the focus go when you close the modal? And so forth.

Ah, and by the way - if you're navigating on the webpage on a keyboard for the first time: There are some patterns to note about keyboard navigation. In WAI-ARIA Authoring Practices, there is a chapter about Developing a Keyboard Interface. In short, the keyboard navigation patterns users expect on the web are borrowed from different GUI-applications. For example, that means that tab-key is usually used to get into the widget, and arrow keys are used for navigation within that widget.

Remediating Issues in Web Solutions

This section has only two subsections - "Level of severity and prioritization of issues" and "recommending strategies and/or techniques for fixing issues." For me, especially the first one was helpful and gave loads of new information.

Some factors influence the priority of an accessibility bug: The severity of the user impact, how fast developers can fix it, business priority, location of the issue, and how often that same bug appears, to name a few.

From these examples, what surprised me was "how fast developers can fix it". I mean, it totally makes sense that the low hanging fruits should be picked and fixed, but I just hadn't thought about it. But then again, according to WebAIM Million, there are automatically detectable WCAG-failures in 98.1% of the top 1,000,000 websites' homepages. Here's percentages of most common types of failures:

Most common types of WCAG 2 failures (Source: WebAIM Million)

WCAG Failure Type	% of home pages in February 2020
Low contrast text	86.3%
Missing alternative text for images	66.0%
Empty links	59.9%
Missing form input labels	53.8%
Empty buttons	28.7%
Missing document language	28.0%

These detectable errors include, for example, missing alt-texts, missing form labels, and empty links, which are relatively easy to fix. It means that when fixing those issues, the accessibility of a website improves a lot.

Summing up

Again, I can't stress enough how much I've learned while studying for the Web Accessibility Specialist-exam. It has opened my eyes to new things in accessibility, and I've found many new tools for making a more inclusive web.

However, I must note that this is only the beginning. Now I have the tools for learning more, but I recognize that the learning must continue. Most of all, I'll need practice, practice, and practice. I've noticed that even if I have all the knowledge, I still keep making those mistakes in code and realize later that I should have known better.

Are you IAAP certified or studying to take the exam? If so, I'd love to hear your thoughts! Also, I'd love to answer if any questions arise about the topic! 😊

Cover photo by Sigmund on Unsplash