Forem: Joe Cannatti

Mentoring With Personality In Mind

Joe Cannatti — Fri, 21 Jun 2019 15:28:12 +0000

I try to approach most interactions with my teammates as a mentoring opportunity. Sometimes this means simple stuff like showing them a command-line trick or a design pattern.

It can also get pretty subtle though.

For example, I recently heard myself say to a less experienced engineer,

“Are you sure you aren’t being too careful?”

Me to a less experienced engineer

I think it was a useful question to ask in that specific situation, but afterwards I found myself reflecting about it. I wasn’t 100% that was the best thing to say.

I don’t think it’s useful for a mentor to try to shape the personality of their mentee to be more like their own.

I don’t think it useful for a mentor to try to shape the personality of their mentee to be more like their own.

Joe Cannatti – me

To some extend, I think that’s what I was doing in that case. I had an instinct going off in my head that we were being too careful about a decision, but that was my own person reaction to the situation.

The goal of being a mentor isn’t to shape someone’s instincts and style to match your own. It’s to help someone do their best work given their personality and instincts.

The goal of being a mentor isn’t to shape someone’s instincts and style to match your own. It’s to help someone do their best work given their personality and instincts.

Joe Cannatti – me

Now, that could still mean that it was the right call to help guide this person in a different direction. However in this case, I don’t think their reaction was coming from a misunderstanding of the elements of the decision or a lack of experience. I think they just felt differently than I did about the situation because of their personality and temperament.

A possible better approach could be to say something like, “I feel like we are being a bit too careful about this. What thoughts and feelings are you working with as we discuss this issue? Do you understand all the key points of the situation? I want to make sure you’re using your efforts in the way that’s most effective for you.”

It’s a subtle change in language, but it’s a different message.

I challenge both mentors and mentees to work with this idea. Can you separate reactions that come from personality and temperament from ones that come from knowledge and experience?

Leave a comment below or reach me on Twitter @joecannatti

Humans Can Code Too: Idempotency

Joe Cannatti — Wed, 19 Jun 2019 02:20:55 +0000

Humans Can Code Too is a content series aimed at anyone who is not coming from a traditional computer science background and is trying to gain a better understanding of software development. This includes those who are just getting starting in a programming career, as well as business people who just want to understand what the hell developers are talking about.

It’s a scary term

Idempotency is a very intimidating word to have someone drop on you in a Pull Request or code review. It sounds super sophisticated and scientific, mathematical even.

The word “idempotency” does come from higher math. However, what a software developer means when they use the word is nothing super complicated.

I’ll give it my own definition

Idempotency – n

When a piece of code can be run multiple times with the same input data without causing undesirable consequences.

Joe Cannatti — ME

In practice, this has to do with what’s going to happen if we find ourselves in a situation where we don’t know if a unit of work was run or not. If the code is idempotent, we can simply run it again. If it’s the second (or 10000th) time it’s been run, that’s fine. It doesn’t cause any problems.

This most often comes up in message-passing based systems and background jobs because those systems involve queues of work. Those queues can result in running code multiple times for a bunch of different reasons. That said, it can be an important feature in almost any situation.

Conceptual Example

At a conceptual level, here’s an example of a non-idempotent way to think about a unit of work followed by an idempotent version.

Pay $100 to the user whose ID is 123

not idempotent

Payout the money for transaction with ID 456

idempotent! Great job

So, what’s the difference between those two?

In the first case, there’s no way to know if the job is a duplicate or not, so if we run that job 3 times, we’re going to send them $300. Businesses usually don’t want to give away extra money

In the second case, on the first run of the code it can say, “Yep, we haven’t sent that money yet, I’ll do it now”, and then on every subsequent run it can say, “Hey, I already did that, I’ll just do nothing”. So you can run that job 1 to infinite times and get the same result.

Example: Pre-calculating Review Count

def increment_review_count(user:)
  user.review_count += 1 
  user.save!
end

That’s not Idempotent! If you run that code 100 times you’re going to increase the review code by 100!

Let’s try a safer example

def calculate_review_count(user:) 
  user.review_count = user.reviews.count 
  user.save!
end

Ah, sweet relief. That one is way better. If you run that 100 times you’re still going to get the right result. The drawback in this example is that it’s also going to be much slower since it needs to read the reviews from the database.

Example: Payouts

def payout(user:, amount:)
  Xtripe.send_payment(id: user.xtripe_id, amount: amount)
end

As we discussed earlier, this is no-good because there’s no way for this code to make sure this money hasn’t already been sent. We can use a transaction record to make this idempotent.

def payout(transaction:) 
  if transaction.should_be_payed? 
    Xtripe.send_payment(id: transaction.user.xtripe_id, 
                        amount: transaction.amount) 
    transaction.mark_as_paid! 
  end
end

That little transaction.should_be_payed? makes all the difference. That method can check if the transaction has already been paid out, as well as check for other conditions.

Example: Backup to S3 (cloud based file system)

def backup_to_s3 
  User.all.each do |user|
    S3::File.write(name: user.id, content: user.to_json) 
  end
end

The problem with this one is that if your job dies part way through, there’s no way to know where we left off without checking in S3.

One way to fix it is to record a timestamp

def backup_to_s3
  User.where('last_backed_up < ?', 1.week.ago).each do |user| 
    S3::File.write(name: user.id, content: user.to_json) 
    user.last_backed_up = Time.now 
    user.save! 
  end
end

We could run this job over and over again and it’s never going to do anything unexpected! That’s what idempotency is all about!

OKRs from a development team’s perspective

Joe Cannatti — Fri, 24 May 2019 18:17:54 +0000

Most of the companies I’ve worked for in the last 5 years have used the OKR system. Although this system was invented in the 70s, it has more recently become popular at Google and has spread through the tech world.

It’s a simple system where the company defines a number of Objectives, and each objective has one or more measurable Key Results. Those KRs are intended to track progress on that objective over time.

For example.

Objective – Increase Customer Retention
Key Result #1 – Lifetime Customer value increase from $N to $N+5
Key Result #2 – Decrease Customer Churn Rate by 10%

Most companies I’ve been at usually have 3-5 OKRs active at any given time.

What OKRs are supposed to do for a company

The idea is basically that everyone has some very clear, direct and measurable goals to align behind. Everything a team does should align to a specific OKR. In theory, that means everyone is rowing in the same direction(s).

It works great at certain levels and in certain ways. For the leadership team, it typically seems to be an excellent mechanism. It can put all the leaders on the same page(s) and provide a great starting point for the quarter.

It can put all the leaders on the same page(s) and provide a great starting point for the quarter.

When it comes time for a dev team make decisions…

Where OKRs become less useful is within the decision making process for an individual team.

Where OKRs become less useful is within the decision making process for an individual team.

Joe Cannatti

The most common pattern I’ve seen goes like this

The team comes in with a backlog of things that they want to work on.
They discuss each item and work out a basic list ordered by priority. The cut out things they know they aren’t going to get to any time soon.
They go over the list and add a label to each task/project to specify the OKR to which it is most closely related.
For the most part, it’s usually works out to be possible to assign an OKR to anything without too much mental gymnastics

Wait a minute… Isn’t that backwards?

Shouldn’t we be using the OKRs to drive coming up with ideas in the first place instead of just wedging them in afterwards?

Yeah, I think that’s the idea.

Backlog

It usually seems to me that the reason it works out this way is because teams generally have large backlogs of things they’ve decided they’d like to do. Most of the stuff in that backlog was written down long before the current OKRs where specified.

So it makes sense that when the OKRs come out for the quarter, we just take what we already have and figure out how to fit it into the OKRs.

Is there anything wrong with that?

Yes and no.

The biggest problem seems to me to be that the team doesn’t end up feeling truly connected or committed to the OKRs. For example, as I write this, I can tell you every project we are going to attempt to work on this quarter, but I can’t even tell you what the OKRs for the quarter are.

We did make them all fit in with OKRs, but it never felt like it was really what was driving us. Maybe that’s okay, but it doesn’t seem super useful to me. I think it gives leadership the justification they need to declare that everyone is working towards the same goals, but I don’t think it leads to dev teams actually feeling like that’s true.

I think it gives leadership the justification they need to declare that everyone is working towards the same goals, but I don’t think it leads to dev teams actually feeling like that’s true.

Ideas to improve how this all works

I have a couple ideas about how you can make this better for the next planning cycle for your team.

Backlog Bankruptcy

When you start the planning for your next cycle, consider abandoning your current backlog. Instead of diving into the things your team has already defined as work that should be done, start totally from scratch.

Drive downward from the OKRs and see if the team can come with ideas that have not already been thought of. Or if they can reframe their existing ideas in meaningful ways to make them truly feel like an extension of the OKRs.

This isn’t easy to do. You will need to continually push people away from stuff that’s already in the backlog, but I think it can lead to better results in the end.

Use OKRs to drive weekly team meetings

Use the OKRs as the starting point for your weekly sprint plannings and other checkin meetings.

Generally, these meetings will naturally follow a pattern of being shaped by the projects and tasks people are working on, but it’s possible to keep pushing the flow of the conversation back to the OKRs.

What effect would this have on your team?

I’d love to hear how you think this could workout on your team. What do you expect would be different if you adopted these techniques? Comment below or reach me at joe@zafulabs.com

What Biz People Need to Know about Tech: Configurable App Platforms

Joe Cannatti — Thu, 16 May 2019 22:10:07 +0000

This is an installment in the What Biz People Need to Know About Tech series. It’s aim is to help non-technical business people to communicate better with engineers and provide better feedback about the value they want them to deliver.

Macro photo of tooth wheel mechanism with CONFIGURATION concept letters

I was recently approached by someone who’s company is struggling to make a technical decision. They are a large organization who has multiple brands under a single umbrella. All of these brands make similar products at different price points and levels of quality. Let’s say they make dishwashers, just for the sake of this post.

The decision this company was wrestling with was whether each of their brands should build separate iPhone apps to interface via bluetooth with their dishwashers, or if they should build one app that can be customized per brand.

This post aims to show what questions a good CTO (or other tech leader) would ask, and how they would use the answers to those questions to make this decision.

Question 1: How Similar Are These Products Going To Be Across Brands?

The answer to this one is not usually as simple as a single value on a scale from 1-10. The ways in which the apps are going to vary matter.

Here’s some examples of variations that are easily supported by a single configurable codebase:

Needing to change colors, fonts, and logos to match each brand.
Needing different copy / content in various places.
Excluding features from some versions of the app. For example, if the lower price point brands don’t have certain features and we want to exlude them from their apps.
Needing to change the order or layout of components.
Using different accounts to authenticate (brand A website accounts vs brand B website accounts)

Here’s some examples of variations that are harder to support with a single codebase.

Needing a totally different control structure for the flow. For example, if one brand wants to use a bottom tabbar based layout and another wants to use a more custom wizard-like flow.
There are wildly different legal requirements. If one want app needs to have special review from a 3rd party agency but another does not, you may not want to tangle both apps up in the regulatory restrictions.
There’s simply no shared functionality at all. If that’s the case, there’s no reason to spend time building the configuration to use a single codebase.

Question 2: Are The Stake Holders For These Products Generally On The Same Page?

By building on a single codebase, you are increasing the amount of communication and agreeance that is needed between the different brand owners.

A good CTO would know to keep an eye out for binding divisions together who are unlikely to work well together over time.

Question 3: Are The Timelines Similar For Each Product?

If there’s one brand that needs to get the app to market much sooner than the others, it may make sense to launch that brand as a stand alone project. You can graft on the configurable elements later to launch the other products.

Question 4: What is the skill level of the team?

It requires more engineering talent to build many apps out of one configurable project. If the team doesn’t have budget for at least a few experienced engineers to guide the development of such a system, it might be wise to build them as seperate apps.

In many cases though, this would indicate the budget is simply not sufficient to set this project up for success.

Making the call

There’s significant long term value in building the apps out of a single configurable codebase. So I would say that if the answers to 2 out of 4 of those questions are indicating it should be built in that manner, it’s the right way to go.

If you have less than 2 of them pointing in that direction, it’s probably worth spending some time trying to get them moving in that direction.

If there’s no way that can happen, you’re best to go with individual apps. However, it should be made very clear that there are serious drawbacks to that approach over the long haul. Praticularly in maintainablity and long term efficiency.

Getting into Software Sales after a decade of Engineering roles?

Joe Cannatti — Sun, 07 Apr 2019 20:54:10 +0000

After 12 years as a software developer, I find myself considering new roles that would reduce or even eliminate my time spent writing code. One of those roles is Sales.

I've spent most of my career working for SF and Valley based startups. I've been successful and have recently made my way into the upper ranks for individual contributors at some great companies.

I've never worked closely with a Sales team and I know very little about what actually goes on in that world. I suspect I could be good at it based on my communication and interpersonal skills.

What I would love to hear from someone who really knows that world is:

Can I make similar money in Sales as I do as a Senior/Principal/Staff engineer in the SF Market?
What does it take to be good at sales in the software industry?
How much would I need to travel?
Is it best done as a full time employee of a company, or as a contractor?

Moving forward after a Code Spike

Joe Cannatti — Sat, 30 Mar 2019 16:30:55 +0000

Writing code is often the best way to figure out what exactly needs to be done to solve a problem. In the Agile world, they call this a Spike.

A spike is when a software developer sits down and starts writing little bits of code with the goal of building a map of all the work they are going to need to eventually do to complete a project.

It’s a way of quickly hacking out code that does stuff like:

Querying the database to see what’s in there and how it fits together
Calling 3rd party APIs to see how they work
Testing the algorithm that Fred said would work in Slack to see if he’s right
Anything else that might need verified before committing to a design.

Spikes usually result in a bunch of messy code that kinda/sorta does most of the things that the product is going to need to do in the end. To most programmers, it feels good to do a spike. It gives more instant gratification than other methods of writing code. It makes me feel like an unstoppable force of nature, slicing through time and space, totally unaware of my colossal mediocrity. Because of that, there’s a temptation to feel that most of the work is done when the spike is done.

What comes next is often the developer saying something like, “I just need to clean up the code from the spike and open a pull request”. This creates the impression that there’s not much work left to do. The bad news is that that impression is often false. The good news is that I’m going to tell you how to deal with that bad news right now.

What’s tangibly different between Spike code and Production code?

All the edge cases. I mean all of them.

One of the main differences between doing a spike and writing production code is what one does when an edge case becomes clear.

In production code, I immediately write a test and/or alter the code to cover that scenario. In a spike, I just keep on rolling. At best, I’ll make a note to myself about it.

These build up over time. Three days worth of hacking out spike code can leave a lot more of these un-handled cases in the code then you might expect.

Long term maintainability

Code written during a spike often has much less thought about maintainability put into it.

Here’s an example from a spike I recently did that involved pulling all data about cohorts of students from an internal API.

def cohort_ids 
  open = cohorts_api_client.search_cohorts(status: 'open', limit: 5000) 
  active = cohorts_api_client.search_cohorts(status: 'active', limit: 5000) 
  upcoming = cohorts_api_client.search_cohorts(status: 'upcoming', limit: 5000) 
  (open + active + upcoming).map(&:cohort_id).map(&:to_i).sort 
end

We had significantly less than 5000 cohorts at the time. So for the purposes of my spike, setting the limit to 5000 and making one call was fine. But what would happen if we had more than 5000 cohorts with any one particular status? That code would miss them. The correct thing to do is to page through the results until there are none left.

The code that actually made it into production looked like this

BATCH\_SIZES = 100 

def all 
  %w(open active upcoming).map do |status| 
    fetch(status: status)
  end.inject(&:+).uniq 
end 

protected 

def fetch(status:, limit: BATCH\_SIZES, offset: 0) 
  batch = cohorts_api_client.search_cohorts(status: status, limit: limit, offset: offset) 
  if batch.count == limit
    batch + fetch(status: status, limit: limit, offset: offset + limit) 
  elsif batch.count < limit 
    batch 
  end
end

That’s a pretty important refactor. It’s also exactly the type of thing that can be easily missed when a coder is rushing to get spike code into production. The spike version of the code will work fine for now. But some day in the future (probably at the worst possible moment), there will be a big influx of new cohorts and that original code would fall on its face. That would shatter the coder’s illusion of having any idea what they’re doing, not just in their work, but in their life. So lets avoid that.

Testability

Spike code is typically not driven by writing tests, or the type of tests used to drive it are not the best kind for producing good designs.

For the spike code listed above, I drove the development with one high level integration test. That single test ran all of the code in the spike end to end. Driving code with unit tests, which execute small portions of the code in isolation, typically leads to much better designs. This ends up being a major cause of the less-than-production-ready-ness of spike code.

What would the PR look like?

Another great thing to think about is what the Pull Request is going to look like. In most cases, without some deliberate effort, it is going to be way too big.

I like to compare the branch with master (or develop) on Github so that I can see exactly what it would be like. That’s a good starting point for understanding that the spike code is in fact, not production ready.

How do we get out of this mess?

1. Take relevant bits of code and put them into some sort of notes document.

I’ll spare you a rant about how I love emacs/org-mode for this sort of thing…

2. Look at each one and type up what it does, how it does it, and (most importantly) what’s not perfect about it.

You might think you already know these things and can skip this step, but don’t!

3. Create a new branch off of master (or develop or whatever) that does not include your spike code.

4. Decide the smallest chunk of functionality that would make for a complete Pull Request

In my most recent spike, I’m aiming to turn it into pull requests that do basically the following

Setup the credentials for accessing the APIs involved
Pulled the data from the apis
Setup the OO design to do the computations on that data
One PR for each field that was computed

There will probably be 5 or 6 separate PRs.

5. Build that functionality. Reach for the code snippets in your notes from your spike as you need them.

6. Take a special pass with each snippet you copy in to make sure all paths through the code are fully covered with unit tests and any short comings that you wrote up earlier are addressed.

This is the most important step!

7. Open that PR, get feedback, make changes, merge.

8. Go back to #3 and repeat until all the work is done

There’s an art to this…

It’s not always going to be easy to do this. For example, Sometimes it will be really hard to break your spike into a bunch sane small PRs. Over time one develops a partly intuitive taste for what’s going to work out best. The only way to develop that taste is to try your best every time you find yourself in this situation.

Good Luck!

What Biz People Need to Know About Tech: Single Page Apps

Joe Cannatti — Sat, 23 Mar 2019 17:02:10 +0000

In the 90s, calling them “Pages” made perfect sense.

Everything used to be so simple. Here’s how web pages worked back in the day:

Type a URL into your web browser.
The browser reaches out to a server.
The server sends you a page of specially formatted text called HTML. The HTML contains the content and a very basic definition of how it should look.
Your browser renders that page.
When you click a link in the page, GOTO #2 (repeat until your Dad makes you sign off of AOL so he can use the telephone).

What is a “Page” in the modern web?

At its core, the web still works that way. However, we’ve pushed the limits of what happens between steps #4 and #5 a great deal. We’ve pushed that part of the process so far that it’s started to change the mental model for the whole process.

Basically, people wanted the web page to do interactive things in between when the browser rendered the page and when the user clicked another link. At first this was pretty simple stuff like making something turn bold when you hover the mouse over of it. Or maybe, letting you hide/show portions of the page.

That’s the origin of JavaScript!

JavaScript is taking over the world. For technologists of a certain age, that’s a weird thing. This is because JavaScript was originally a quick hack added into the Netscape web browser to make enhancements and minor interactivity possible on a web page.

It was never meant to be a programming language that entire careers, products, and empires are built upon. It was originally just a way to embed a little bit of logic into a web page.

A single page app is kind of like a desktop application that runs in the browser

A single page app is essentially a web page that builds an entire user experience without ever asking the server for a new page. Basically, the first page loads an app written in Javascript. That app loads new content, sends data to the server to be saved, and does everything else that we see in modern web apps.

Another way to say it is that we now build whole apps out of the little tool intended to let you make something bold when the mouse hovers over it.

There was a time when this was really radical and difficult. These days though, it’s becoming totally sane and standard.

It’s even becoming practical to write highly sophisticated apps like photo editors and animation tools in JavaScript and run them in the web browser. These types of products used to require building desktop applications that had to be installed and licenced on the end user’s machine.

Where’s the business value?

The most direct line to business value is through the enhanced level of interactivity made possible. Here’s a good question to ask yourself, “is my product and interactive application or a series of dynamically generated pages?”.

For example, a product that to me seems like an obvious choice to build as a single page app is Todoist.

The user is spending all day in the interface managing their todo list. There are many complex interactions like tagging, scheduling, commenting, ordering, etc. Every millisecond that you can shave off of the user’s experience is going to make a difference in how productive they can be.

Todoist is implemented as a single page app. It also has a desktop wrapper that runs that single page app as a stand alone instance. That all makes perfect sense for the type of product that it is.

When do you not want a single page app?

If your product fits perfectly fine into the basic link->page->repeat model, then you’re probably better off building it that way. That pattern is simpler, cheaper, and easier to maintain than the Single Page App pattern.

If you’re not going to reap any benefits from a highly interactive experience, then you want to try to avoid taking on the extra overhead of building your product as a single page application.

Hybrid approaches

It’s possible to blend the link->page->link->page approach and the SPA approach. For example, you can have a basic page model but include a user dashboard that is implemented as a SPA within the context of the other pages.

In practice, this approach has some subtle drawbacks that cost you some of the benefits of a SPA, but can be a great compromise in some cases.

Wrap up

I hope that gives you a good overview of what it means to use a Single Page App approach in building a product. With this knowledge, you should be able to engage in conversation with your technical team about whether or not this pattern is right for your company.

I hope you checkout the next installment of What Business People Need to Know About Tech!

In Praise of Multiple DB setups and Rails 6

Joe Cannatti — Mon, 18 Mar 2019 13:35:02 +0000

It looks like Rails 6 is going to include first class support for configuring your app to talk to multiple databases. I’m not going to get too deep into how the feature will work in this post. I think there will be plenty of blog posts and documentation discussing that once it’s released. I want to spend some time explaining why you’d want to access multiple databases from a single web app.

Read Only Connections and Follower databases

One common use case for connecting a web applications to two databases is to have one connection to the primary read/write instance of the database and another connection to a read-only replica of the same data. This is highly useful when trying to scale a system because it allows you to move complex read queries off of the primary database.

This reduces contention between reads and writes and leads to better performance. If you have a background job that computes some information about your user, you can have that background job use the follower for the read queries.

There will always be some level of lag between the primary db and its read-only follower, so systems have to be designed with that in mind to make this strategy usable. For example, you have to build things in such a way that it doesn’t create problems if a record has been added to the database but it hasn’t yet been copied to the read-only follower. That new record has to be able to be picked up on a subsequent run of the code.

ETL, Precomputation, and Other Data Warehousing Principals

Another set of designs that can be elagently implemented by having a web app that connects to multiple databases comes from the world of data warehousing.

One of the most common designs from this family is used when complex data transformations are computed ahead of time to simplify the computation that is needed in real time.

For example, imagine that we need to do a complex calculation to determine if the logged in user has a special gold status. Something like, “have they made 5 purchases in the last 60 days, written 3 product reviews, and completed 100% of their user profile”. That isn’t something that you’d want to query for on every page load.

Computing that value ahead of time is a good solution to this type of problem. If you combine this with the previous suggestion of connecting to a read-only follower of the database, you can end up with a great solution where a background process reads from the read only follower, makes this complex calculation, and writes it to a database specifically used to store precomputed values. This makes it so that your primary read-write database isn’t burdened in anyway by this relatively expensive computation.

It works similarly for business analysis and reporting use cases.

Monolith -> Microservice Transition

Another excellent time to consider connect your app to multiple database is when you are beginning to break a large Monolithic application up into smaller components.

Let’s say for example you are planning to pull all of your user information from the main monolith into a User Microservice. One way you could approach that is to first move the data from the primary database into one that will be private to the new service. That’s going to cause you to need to refactor all the places that you are relying on database joins to the user table. That approach is no longer going to be possible once you transition to the service. You can then make a Ruby class that provides an interface to that data. This class will read the data from the new database.

Then once you spin up the User Microservice, you can simply refactor that class to read from the JSON API instead of the new database. Then, you make it so that the User Microservice is the only thing that connects to the new user database.

This is a very common, safe, and powerful way to evolve your architecture.

Wrap up

Rails 6 is introducing a feature that may make all of the designs discussed in this post easier to setup. It’s a great time to do some thinking about how your system could benefit from these sorts of designs.

I’d love to hear how you use multiple database setups in your systems. Comment below!

What Biz People Need to Know About Tech: Test Driven Development

Joe Cannatti — Mon, 11 Feb 2019 22:59:06 +0000

This is an installment in the What Biz People Need to Know About Tech series. It’s aim is to help non-technical business people to communicate better with engineers, and provide better feedback about the value they want them to deliver.

What is it?

Test driven development (commonly called “TDD”) is a technique that software developers use to get their work done. If you’ll allow me to make a music analogy, it’s like a guitar player using a pick to play a certain part as opposed to playing it fingerstyle.

If you’re a golfer, it’s like using a 65° wedge instead of a regular pitching wedge to sink a chip shot.

If you’re a rutabaga farmer, it’s like using nutrition blend 75 and double pruning instead of using the Barry Garbo method.

Okay… That rutabaga farming one isn’t real. I have no idea how to grow a rutabaga… but you get the idea.

What kind of technique?

Writing code can be tricky because we often need to satisfy a bunch of different behaviors with the same code. For example, let’s imagine that we are writing some code that calculates the total amount a customer owes at checkout time.

If you just dive in and start writing that code, it will probably go something like this

I’ll make it sum up the price of all the items in the cart
Next I’ll call the 3rd party service to calculate the tax.
Then, I’ll make it so any account credit they have is deducted.
Next, I’ll make it deduct the value of a coupon if the user has one.
Oh wait, do they need to pay tax on the value before or after I apply the coupon?

It can be kind of like a cartoon character trying to plug leaks in a boat. Do you remember this? (I can’t find it on YouTube). A leak springs up and the character puts their finger in it to plug it. Then another pops up on the other side of the boat and they have to stretch to use their other hand to fix that one. Then they have to use their toe for the third, and so on.

Sometimes you get yourself in a situation where every time you make Thing A work, you break Thing B.

In our example above that would be like breaking the account credit calculation every time you make the coupon work, and then breaking the coupon when you go back and fix the account credit.

TDD lets the coder specify all of the things that the code needs to do before she writes the code itself. Those specifications exists forever and can be re-checked every time the code is changed.

Also, in 6 months when the developer has long forgotten if the coupon value is supposed to be taken out before or after the tax is calculated, the tests are still there to make sure everything still works correctly.

This effects the end product

A developer has to do things a little differently to do test driven development. It’s possible to write code that is hard or impossible to test. When a programmer is using TDD it causes the code to be designed in a different way.

The ways that the design is effected by TDD are almost always positive. I’m sure there’s some obscure situation where an un-testable design would be considered better, but I can’t recall ever encountering that situation in real life.

In practice, TDD improves code design.

What’s the value to the business?

The value to the business comes in two flavors:

Less errors and bugs in production
Faster development time

Long Term vs Short Term

Notice above that I said TDD makes development faster. Some people will say it a bit differently. They’ll say that TDD costs more time in the short term and saves time in the long term.

That’s technically true, but in my experience the balance point comes so soon that it’s more accurate to say that it’s just always faster. If the code I’m working on is going to be worked on for more than one day, I do TDD.

Test First vs Test After

Above I said that you write the specifications for the code before you write the code itself. That’s not the only way to do it, you can also write the tests afterwards and alter the code if what you started with doesn’t turn out to be easy to test.

Most developers do a mix of test-first and test-after development. I’m still okay with calling that TDD, although some people will say it’s only TDD if you write the tests first.

Do you have to do it to write good code?

Nope. Tons of companies get by without this particular technique in their tool belt. However, it’s becoming a pretty bad sign to not have tests as a part of you code base.

For the most part, once a developer learns to do test driven development well, they never go back to any other method.

There can be some… dogma

Developers can get “passionate” about this stuff….

I’m not sure that’s a good thing. TDD is a tool and tools are meant to help a person achieve a goal. TDD is not a goal in itself. Personally, I’m most impressed with a developer when they have laser sharp TDD skills, but understand that it’s just a way to build great stuff.

Developers who never learned to do it

It takes a long time to get good at test driven development. For an experienced developer who has years of experience writing code in a different way, it can feel like trying to throw a baseball with your wrong hand.

Because of this, you’ll run into people who have some pretty incorrect ideas about it. It can be good to ask someone how much TDD they have done before asking them what they think about it.

As I said above, it’s very rare that someone gets the hang of it and then decides they don’t want to do it anymore.

Summary

These days, you pretty much always want your developers to be writing tests. The tooling and learning materials have advanced to the point that it’s typically very easy to setup a test friendly development system.

It helps the business by making the development team able to move faster (over the long term) and by reducing errors.

It can be tricky to talk about this stuff with developers for a few reasons. They can be way too enthusiastic about it and forget that it’s just a tool. They can be defensive about it if they’ve never learned to do it. Generally, you want someone who can talk about the benefits of TDD, but doesn’t give off the vibe that it’s more important to them than the product itself.

I hope this was helpful to you. I hope you come back to read the next installment of What Biz People Need to Know About Tech.

Refactoring Example: React Component

Joe Cannatti — Wed, 19 Dec 2018 19:45:54 +0000

This post is a quick lesson, by example, of how to refactor a React component to keep business logic out of the view layer.

One component of a product that I’m currently developing is a micro meditation reminder. This component allows the user to set an interval in which they want to do 3 different types of meditation.

Once the interval is set, a textbox shows how long the user has until it’s time to do that meditation. When the timer reaches 0, a browser notification is displayed and the timer resets.

The component is fully functional, but all of the logic about how the timer works is directly embedded in the React Component object. This is not a great design because it makes it hard to test any functionality in isolation. As such I only have one test currently. That test drives the changing of the Interval field in the DOM and asserts that the Next field updates.

We are going to use TDD to refactor this component such that the timer logic no longer lives directly in the component so that we can have a sane and testable interface.

Here is the code and the test we are starting with.

class MeditationListItem extends Component {  
  constructor(props) {
    super(props);
    this.state = {interval: 0, nextIn: "not scheduled"}
  }

  componentDidMount() {
    this.timerLoopID = setInterval(this.timerLoop.bind(this), 100);
  }

  componentWillUnmount() {
    clearInterval(this.timerLoopID);
  }

  intervalUpdated(event) {
    const interval = event.target.value;
    this.setUpTimerForInterval(interval);
    this.calculateNextIn();
  }

  setUpTimerForInterval(interval) {
    const nextAt = moment().add(interval, 'minutes');
    this.setState({ interval: interval, nextAt: nextAt });
  }

  calculateNextIn() {
    if (this.state.nextAt) {
      this.setState({nextIn: this.state.nextAt.from(moment()) });
    }
  }

  timerExpired() {
    showNotification(this.props.name);
    this.setUpTimerForInterval(this.state.interval);
  }

  timerLoop() {
    if (this.state.nextAt) {
      if (this.state.nextAt < moment()) {
        this.timerExpired()
      }
      else {
        this.calculateNextIn();
      }
    }
  }

  render() {
    return (
      <ListItem>
        <ListItemText primary={this.props.name} />
        <TextField
          label="Interval (Min.)"
          margin="normal"
          type="number"
          defaultValue='0'
          onChange={this.intervalUpdated.bind(this)}
          className="interval-field"
        />
        <TextField
          label="Next"
          value={this.state.nextIn}
          margin="normal"
          className="next-in"
          InputProps={{
            readOnly: true,
          }}
        />
      </ListItem>
    )
  }
}

export default MeditationListItem

The first thing that jumps out to me when I think about refactoring this is that the stuff we want to remove from the React Component is the timer logic. So, I’m going to create a class called MeditationTimer and use unit tests to drive the development of its interface.

We know the MeditationTimer class is going to need to know about the name of the meditation and the interval in which we want it to go off, so lets start with that

class MeditationTimer {
  constructor(name, interval) {
    this.name = name;
    this.interval = interval;
  }
}

export default MeditationTimer

And drive that via a test

it('can be instantiated with name and interval', () => {
  const meditationTimer = new MeditationTimer('test', 5);
  expect(meditationTimer.name).toEqual('test');
  expect(meditationTimer.interval).toEqual(5);
});

What else needs to go into this new class?

Well, it’s almost everything else in the React Component except for the markup!

The next thing that I’m going to move is the calculation of nextAt and nextIn

Those are the key values that makeup the state of the component.

I’m going to do that in a function called timerState()

class MeditationTimer {
  constructor(name, interval) {
    this.name = name;
    this.interval = interval;
    this.nextAt = moment().add(this.interval, 'minutes');
  }

  timerState() {
    return {
      nextIn: this.nextAt.from(moment()),
      nextAt: this.nextAt,
      interval: this.interval
    };
  }
}

 describe('timerState()', () => {
  let startingMoment;
  let meditationTimer;

  beforeEach(() => {
    startingMoment = moment();
    meditationTimer = new MeditationTimer('test', 5);
  });

  it('sets nextAt on initialization', () => {
    expect(meditationTimer.timerState().nextAt.isAfter(startingMoment)).toEqual(true);
  });

  it('sets interval on initialization', () => {
    expect(meditationTimer.timerState().interval).toEqual(5);
  });

  it('calculates nextIn when called', () => {
    expect(meditationTimer.timerState().nextIn).toEqual("in 5 minutes");
  });
});

Looks pretty good.

Next is the timer loop itself

I’ll drive that out using tests like so

class MeditationTimer {
  constructor(name, interval, callback) {
    this.name = name;
    this.interval = interval;
    this.callback = callback;
    this.setNextAt();
    this.notify = showNotification;
  }

  start() {
    return this.timerLoopID = setInterval(this.timerLoop.bind(this), 100);
  }

  stop() {
    return clearInterval(this.timerLoopID);
  }

  setInterval(interval) {
    this.interval = interval;
    this.setNextAt();
    this.callback(this.timerState());
  }

  timerState() {
    return {
      nextIn: this.nextAt.from(moment()),
      nextAt: this.nextAt,
      interval: this.interval
    };
  }

  private

  setNextAt() {
    this.nextAt = moment().add(this.interval, 'minutes');
  }

  timerExpired() {
    this.notify(this.name);
    this.setNextAt();
  }

  timerLoop() {
    if (this.interval > 0) {
      if (this.nextAt < moment()) {
        this.timerExpired();
      }
      this.callback(this.timerState());
    }
  }
}

export default MeditationTimer;

const mockCallback = jest.fn();

beforeEach(() => {
  startingMoment = moment();
  meditationTimer = new MeditationTimer('test', 5, mockCallback);
});

describe('setInterval', () => {
  it('updates interval and calculates nextAt', () => {
    const originalNextAt = meditationTimer.timerState().nextAt;

    meditationTimer.setInterval(6);
    expect(meditationTimer.interval).toEqual(6);
    expect(meditationTimer.timerState().nextAt.isAfter(originalNextAt)).toEqual(true);
  });
});

describe('timerLoop', () => {
  describe('when interval is 0', () => {
    it('is a no op', () => {
      meditationTimer = new MeditationTimer('test', 0, mockCallback);
      meditationTimer.timerExpired = jest.fn();
      meditationTimer.callback = jest.fn();
      meditationTimer.timerLoop();
      expect(meditationTimer.timerExpired).not.toHaveBeenCalled();
      expect(meditationTimer.callback).not.toHaveBeenCalled();
    });
  });

  describe('when interval is 1', () => {
    it('calls the callback', () => {
      meditationTimer = new MeditationTimer('test', 1, mockCallback);
      meditationTimer.callback = jest.fn();
      meditationTimer.timerLoop();
      expect(meditationTimer.callback).toHaveBeenCalled();
    })
  });

  describe('when timer is expired', () => {
    it('resets the timer', () => {
      meditationTimer = new MeditationTimer('test', 1, mockCallback);
      meditationTimer.nextAt = moment().subtract(1, 'day');
      meditationTimer.notify = jest.fn();
      const originalNextAt = meditationTimer.timerState().nextAt;
      meditationTimer.timerLoop();
      expect(meditationTimer.timerState().nextAt).not.toEqual(originalNextAt);
    })
  });
});

describe('start and stop', () => {
  it('starts and clears a js interval', () => {
    const timerId = meditationTimer.start();
    expect(timerId).not.toBeNaN();
    meditationTimer.stop();
  });
});

Now, we have 100% test coverage.

And our React Component contains nothing expect what a view should!

class MeditationListItem extends Component {

  constructor(props) {
    super(props);
    this.state = {interval: 0, nextIn: "not scheduled"}
    this.timer = new MeditationTimer(this.props.name, 0, this.timerStateUpdated.bind(this));
  }

  componentDidMount() {
    this.timer.start();
  }

  componentWillUnmount() {
    this.timer.stop();
  }

  intervalUpdated(event) {
    this.timer.setInterval(event.target.value);
  }

  timerStateUpdated(timerState) {
    this.setState(timerState);
  }

  render() {
    return (
      <ListItem>
        <ListItemText primary={this.props.name} />
        <TextField
          label="Interval (Min.)"
          margin="normal"
          type="number"
          defaultValue='0'
          onChange={this.intervalUpdated.bind(this)}
          className="interval-field"
        />
        <TextField
          label="Next"
          value={this.state.nextIn}
          margin="normal"
          className="next-in"
          InputProps={{
            readOnly: true,
          }}
        />
      </ListItem>
    )
  }
}

export default MeditationListItem