Forem: Katie-Lynn (KL)

Why you should take more time to write good test names

Katie-Lynn (KL) — Fri, 05 Aug 2022 14:18:00 +0000

We all know writing good tests is important. We all know having high test coverage is important. Sometimes we can forget that writing good test names is important too.

Imagine we are building out a form to submit a user’s account settings. This form includes contact information, branding colours, and a logo image.

Let’s use this simple example to highlight three reasons why we should all take more time to write thoughtful test names:

1. Help reviewers provide better feedback

Meaningful test names help others better understand the intention behind the code. Reviewers can then provide possible alternatives to achieve that intention. They can also ensure you consider appropriate edge cases.

In our form we want to allow users to customize their account by selecting from a list of colours. To make it simple we decide to use all the default css colours in the select list. We created a helper method to turn them into correctly formatted words.

 PASS  src/util/convertToSpaceCase.test.js
  convertToSpaceCase helper
    ✓ converts camel case string to space case string

The initial description of the test describes what is expected to happen but not necessarily the intention of this utility function. The feedback we might receive:

Should this helper method also be able to handle other use cases? Kebab case, pascal case, snake case, etc?

This is a good question, but it doesn’t help us build a better form for our users. This could lead to wasted time and effort. If the test highlighted the intention, this could generate other questions.

 PASS  src/util/convertCssColorToDisplayString.test.js
  convertCssColorToDisplayString helper
    when provided a css color
      ✓ generates a displayable color name

The feedback we might now receive:

Should we use this well maintained external library for displaying css colours?
Are we following our content style guide with the outputted colour names?

The review is now more focused on the intention of what we are building. This should lead to a better experience for our users. The feedback could still request this become a re-usable generic utility component. But we do know the reviewer understands the intent.

2. Allow non-engineers to provide feedback

Next we want to build a phone number input component for our form. The requirements for this input include:

If a valid phone number is entered it should display the number in a phone number format (ex: +X (XXX) XXX-XXXX)
If not a valid phone number is entered we display an error message.

The tests we write for this component, keeping them as readable as possible, may look like this:

 PASS  src/components/PhoneNumberInput.test.js
  PhoneNumberInput component
    when provided string with phone number
      ✓ displays properly formatted phone number
    when provided string without phone number
      ✓ displays an error message

Our Product Manager can easily align our work with their acceptance criteria. Our Designer can see considered edge cases. This could spark discussion:

What happens if the phone number is valid but missing a country code?
What happens if the phone number copied-pasted into the input and includes special characters?

The resulting conversations help ensure your team is building a good solution. We can improve our phone number input component and update our tests.

PASS  src/components/PhoneNumberInput.test.js
  PhoneNumberInput component
    when provided string with phone number
      with just numbers
        ✓ displays properly formatted phone number
      with special characters
        ✓ displays properly formatted phone number
      without a country code
        ✓ displays properly formatted phone number with North American country code
    when provided string without phone number
      ✓ displays an error message

3. Save other’s time

Lastly we want to ensure that only administrators can access this account settings form.

PASS  src/features/AccountSettingsForm.test.js
  AccountSettingsForm page
    when user is an admin
      ✓ form is displayed
    when user is not an admin
      ✓ user is redirected and shown an error message

This is extremely simple example. But this test (and all the tests above) will provide a lot of information for our fellow engineers. Engineers working in this code in the future can quickly learn how this feature should work. They may even share with their PM or Designer. For example:

“Ah! To test out this form, first I’ll need to make sure I am logged into my test account as an Admin.”
“We are opening up accounts to European countries. I’ll let my Product Manager know we currently default our phone number country code to North America.”

Conclusion

I hope these examples have highlighted the extra value our tests can provide. Clear and descriptive test names are a great resource for both developers and non-developers alike. We can:

better focus on the value we are trying to provide our users
collaborate with our whole team to improve the experience for our users
help others quickly understand the expected user experience

I hope this article encourages you to take an extra few minutes to re-review your test names the next time you write a test.

What does "trusting your gut" look like?

Katie-Lynn (KL) — Wed, 16 Mar 2022 17:50:57 +0000

At good companies you succeed and you fail together. Everyone is contributing and making decisions with the best intentions. Everything is in service to the company's (and therefore your own) success. And sometimes we fail and that is okay! Failure provides great learning opportunities. But what about the failures where you think to yourself "I knew that was going to happen..."?

You remember this feeling in the pit of you stomach early on in the project. Maybe it was during a story mapping session or a technical spike and you knew something was missing. I hope you trust your team and were able to share you concerns immediately. Maybe you did, but couldn't clearly articulate the issue so you let it go. Or maybe you didn't share for other reasons. Either way you might be thinking "I wish I had done more X months ago when I had that feeling". Trying to reflect back you might ask "Why didn't I? Would we all be in a much better place if I had?"

Reasons you may not have shared your concerns:

I am not as experienced as others on my team so they must be right.
I am new/inexperienced, I don't want to waste people's time with my silly questions.
I am tired of conflict, or the back and forth so I am just going to give up.
I want to be able to trust my teammates so I am just going to let them carry out the plan as they see fit.
That is not my job.

None of these are valid reasons. That gut feeling in the moment is an important tool you get for free. As Gail Goodman said at Jobber's Own Your Impact day "Frustration is a clue to investigate". So take time to understand that feeling. Get good at noticing and understanding that feeling.

Your first step should be to better understand the "whys" of the project. Read through the project documentation. Try connecting one-on-one with the Product Manager or the Lead Engineer. Go through what decisions have been made and why. This might immediately resolve your concerns! And you can confidently move forward with the project. Or you may have a clearer understanding of your gut feeling. In either case record and share the results of what you understand so far and the outstanding questions - even a simple slack post to your team. This is beneficial for three reasons:

Your teammates can confirm that your understanding is correct or add clarification.
Your other teammates can stay aligned on the “whys” of the project (they might even have similar concerns).
With your new understanding you can better articulate and start a discussion to address your concerns.

The whole team is now in a better place, the “whys” have been reiterated and your specific concerns have been shared. But why else should you always share your concerns? Let's rephrase the above reasons not to:

I am not as experienced as others on my team but they have a lot on their plate and may not have considered X,Y, and Z.
I am new/inexperienced and this is a great opportunity for me to learn. At the very least, the whole team will better understand the "whys" of the project.
I am tired of the back and forth, so let's document the risks and potential impact of not addressing these concerns. If needed, setup monitoring and define a contingency plan. With a plan in place we can continue on with the project as is.
I want to be able to trust my teammates so I am going to ask good questions to help the whole team stay aligned and help ensure they succeed as they carry out their plan.
That is my job, I need to share my concerns to better help my team and the company succeed.

Let’s go through an example:

My team was spiking out and planning optimizations for a poor performing component in our mobile app. I understood the importance of this work, our customers were frustrated. But I started getting an uneasy feeling. So I setup time to chat with my team's Product Manager to better understand the problem. During that discussion I realized that we hadn’t identified the true source of the performance issues. We were planning a number of improvements but we hadn’t verified if they would address the root cause of the problem. As a result we decided to add those outstanding questions into our in-progress spike. The whole team then worked on getting answers before moving forward with the right solution. If we didn't have this chat now, we could have risked weeks or months of work building solutions that might not have actually improved the experience for our customers.

So next time you have that gut feeling use it! It is an important tool you can get better with over time. David Epstein notes in his book Range: Why Generalists Triumph in a Specialized World that good teams are responsible for protesting if something doesn't feel right. This is even more important when dealing with unknowns.

What do you do when your gut starts talking?

About Jobber

We are hiring for remote positions across Canada at all software engineering levels!

Our awesome Jobber technology teams span across Payments, Infrastructure, AI/ML, Business Workflows & Communications. We work on cutting edge & modern tech stacks using React, React Native, Ruby on Rails, & GraphQL.

If you want to be a part of a collaborative work culture, help small home service businesses scale and create a positive impact on our communities, then visit our careers site to learn more!

The Real Job: Managing Uncertainty and The Unknown

Katie-Lynn (KL) — Tue, 30 Nov 2021 18:43:02 +0000

There are an endless amount of things to learn as a software developer. It can be difficult to know what to focus on to ensure you advance in your career. Learning to manage uncertainty and the unknown is one of the most important skills to master. Experienced developers quickly (and effectively) identify, reduce, and plan for uncertainty.

What does managing uncertainty look like?

Early on in a developer’s career the amount of what is not known can be overwhelming. To combat that feeling one can become eager to learn as much as possible as fast as possible. This will lead to burn out and can even cause stagnation. Instead start by identifying the specific uncertainty that needs addressing.

Let’s use a made up example: Christine is a junior developer who is two months into her first software development role at Company ABC. She is uncertain about many things, including how to use her new tools, the processes that Company ABC has for releasing features, and just general best practices. Christine lists out everything she doesn't know and selects the top 3. Christine uses Edmond Lau’s definition of leverage to decide what is most important (to learn more check out his book The Effective Engineer). There will be a long-lasting impact on Christine’s team if she can resolve or reduce these 3 uncertainties:

How can I better use my integrated development environment (IDE) to read and write code faster?
How can I write better tests to ensure quality code coverage?
How can I understand a new area of the code base to prepare for upcoming work?

Next she refines this list to be more specific:

How can I better use my IDE to read and write code faster?
What are the quick keys to search and find code in my IDE?
What are the code completion and templating tools in my IDE?
What add-ons or tooling can I add in my IDE to auto generate common code snippets?
How can I write better tests to ensure quality code coverage?
What resources can I use to practice working within our testing framework?
What is Company ABC’s testing strategy?
What golden examples do we have available to reference?
How can I understand a new area of the code base to prepare for upcoming work?
What current resources and subject matter experts are available?
What does the data structure look like and how is it displayed to our users?
What do the tests say about how this code should work?

These will be easy to address! Christine can search existing developer blog posts and technical guides on the internet. She can also use company resources and ask her coworkers for support. She schedules 30 minutes everyday, for the next two weeks, to investigate these questions. She also uses that time to practice what she learns. Christine does a walk through of the new area of code with Jerry, who is very familiar with the code. She now understands at a high level how that code works. She is prepared for the upcoming work.

It's now time to estimate and plan the next increment of work with her team. Christine shares what she understands of the work and what she knows she still needs to learn. She also shares her new reduced capacity and that she will be taking 30 minutes everyday to learn and improve.

The team strategizes about how to tackle that upcoming work. They decide a senior developer will pair with Christine. This plan will ensure that the work gets done on time. It also ensures she has immediate support in understanding the remaining code uncertainty.

How do experienced developers manage uncertainty?

The uncertainty grows as software developers progress in their career. The resources available to reduce that uncertainty shrink. And the type of uncertainty changes.

Let's fast forward 10 years and Christine is now a senior developer tackling new problems. She is ready for the unknown. She is currently investigating how to integrate SMS into Company ABC’s mobile app. She suspects that delivering this project will require significant effort. To prepare for this project Christine starts to list out everything she doesn’t know.

There are many techniques to identify and prioritize project uncertainty. One great way is story and assumption mapping explained by Teresa Torres in her book Continuous Discovery Habits. Christine generates her list by considering her past projects. The “surprises'' in other large projects were great learning opportunities. Checkout how Jobber learns from “surprises'' in this article about Post Mortems. Christine also asks her Designer, her Product Manager and subject matter experts at Company ABC to refine and add to this list.

SMS in the mobile app project:

How can we immediately show new SMS in the UI when user is looking at the app? Does our existing infrastructure enable this?
How can we send a push notification to our users when they receive a new SMS?
How can/should we track usage of SMS in the app?
How can we …

Next Christine works with her team to identify the riskiest uncertainty in the list. These are questions that, if answered "no" or "not possible", would stop the project. They are often about the feasibility of a solution. By answering these questions up front the team won’t waste time on an impossible project.

Christine schedules time for her team to answer these specific questions. The answers look promising so she then organizes a mini-hackathon. This is a time-boxed event for her team to build a working prototype as fast as possible. Christine and her team complete this work with a better understanding of the code. They also reduced some secondary uncertainties, including the decision on whether to use a library or build a UI to display SMS. And lastly, they add new uncertainties they discovered to the list.

Christine can use what she now knows (and what she now knows she doesn't know) to better estimate and plan work. Her team estimates the work considering time to develop, resources and the remaining uncertainty. She assigns higher estimates to the parts of work with higher uncertainty. Next she provides a realistic project timeline to her stakeholders. The SMS in the mobile app project will take 3 to 4 months considering existing commitments.

It's unrealistic to reduce all uncertainty up front. Christine plans to tackle the parts of the project with the highest uncertainty first. Christine and her team can inform their stakeholders about new discoveries as early as possible. Then together they can decide to adjust the project timelines or pivot to a different project.

Why is this important?

Identifying, reducing, and planning for uncertainty allows companies to better compare projects. Companies can identify the higher leverage projects to work on now. Managing uncertainty well also allows teams to build and maintain trust with stakeholders.

Christine has successfully delivered on her last two projects. Her stakeholders at Company ABC are confident she will meet her commitment with this new project. They can appropriately plan their own work around the 3 to 4 month timeline.

To be successful like Christine, start accepting and welcoming the unknown. It’s in this uncertain space where important growth opportunities live.

How well do you manage the unknown?

About Jobber

We are hiring for remote positions across Canada at all software engineering levels!

If you want to be a part of a collaborative work culture, help small home service businesses scale and create a positive impact on our communities, then visit our careers site to learn more!