7. Communication – Refactoring at Scale

Chapter 7. Communication

A friend of mine, we’ll call her Elise, recently embarked on a house-building journey. Over a period of several months, Elise became intimately involved with every step of the process. She coordinated with plumbers, electricians, carpenters, tile-layers, and countless crews cycling in and out of her build site. Each of these professionals worked in tight-knit teams, bringing her home to life, piece by piece.

Every so often, some of Elise’s friends, like me, would ask her how the house was coming along. She’d launch into an epic tale about the bathroom tiles, pulling out pictures of samples she considered, detailing the many phone calls required to replace the original batch when most of them arrived cracked. Then she’d realize she hadn’t told me about the plans for the second bathroom and pivot to a new set of anecdotes.

I did love hearing about how her house was coming along, but Elise’s nonlinear storytelling, coupled with the grueling detail, was a bit too much for me (and many of her other friends). So, after a few conversations, we asked her to start a blog. There, she could document the progress, complete with pictures and arduous detail, and we could periodically check in and casually browse at our leisure. We’d found a way of keeping up with the construction in a medium that worked for everyone.

Elise has a direct, detail-oriented approach in her everyday communication with the construction crews, and more of a big-picture approach in her blog. With a large refactoring project, you have to manage communication hurdles from two distinct perspectives as well: first, within your own team (Elise with her construction crew), and second, with external stakeholders (Elise with her friends). In this chapter, we’ll discuss communication techniques you can use to keep both groups informed and aligned. We’ll look at important habits you should establish for your team, and some tactics for fostering a productive team. Then we’ll look at what measures you should be taking to keep individuals outside of your team in the loop. We’ll also discuss some strategies for coping with stakeholders that are either too hands-on or not hands-on enough.

The ideas in this chapter are meant to give you a blueprint for developing strong communication habits on your team. Your company might already have well-established practices around the way large, cross-functional software projects are coordinated, tracked, and reported on. Your manager, product manager, or technical program manager may also have their own ideas of how best to set up your team for success. I recommend listening to these individuals, reading the ideas that follow, and piecing together something that you believe will work best for everyone. Hopefully by the end of this chapter, you’ll have a new set of tools ready to use for your next large refactoring project.

Within Your Team

Communication within your team is hopefully already low-friction and frequent. If so, your team is probably participating in a number of exchanges during a regular workday. You’re pair-programming, reviewing each other’s code, and debugging together. Your team might also have daily stand-up and weekly sync meetings. Many of us don’t think about how we’re communicating when we’re partaking in these interactions. They simply feel like a routine part of our job, as they should. However, some of these interactions could be made a little bit more deliberate to support longer-term, technically complex projects better (like a large-scale refactor.)

To keep your team moving forward, free from misunderstandings and other mishaps, there are a few communication habits you should consider implementing from the very start. Some of these concepts will be familiar to those who practice Agile, even minimally. We’ll look at both high-frequency habits (i.e., on a daily or weekly basis) and low-frequency habits (i.e., on a monthly or quarterly basis) that are important for taking a critical look back at what you’ve accomplished to date and what still lies ahead.

Tip

If possible, I recommend instituting a policy of no laptops and minimal phone usage during meetings. Ideally, the only people who should be using a laptop during a meeting are those actively participating by either taking notes, or sharing content on their screen. If a meeting attendee is on call or actively contributing to incident remediation, having a laptop out is more than fine. This policy might sound a bit rigid, but I truly believe that it can benefit everyone. I find that I maintain much better focus during meetings I attend without my computer; I listen more attentively, offer better ideas, and more often leave the meeting feeling that it was productive. If you’re curious to give it a try, start out by instituting the policy for just one or two meetings. You might find that they’re more productive and, on occasion, end earlier!

Your team is probably communicating pretty frequently in a number of unique ways. During your typical workday, you’re probably chatting, pair-programming, reviewing code, and debugging together. There are some more regular, structured means of communication that can be meaningful to make sure that everyone is checking in at a good cadence. We’ll outline a few here and describe how they can be valuable.

Stand-Ups

Stand-ups are a great habit for keeping everyone on the team aligned at regular intervals. They can be a good forcing function for you and your teammates to update the status of your tasks within your project planning tool. Stand-ups are also a great opportunity to reflect back on the past 24 hours; have you made sufficient progress or should you reach out to a teammate for a helping hand? Given what you learned yesterday, what do you plan to do today?

Every team has a different approach to stand-ups. Some folks prefer an in-person meeting where everyone gathers around their desks and recites their progress from the day prior. Requiring everyone to be present for stand-ups at a regular time every day has its advantages. They provide engineers with a daily anchor point around which they can plan their work.

When working on large software projects, having a designated time when you can take stock of the progress you’ve made, however small, is crucial. Sometimes the scope of the effort can seem overwhelming, and being able to focus on incremental steps forward can make it feel more achievable. Daily, in-person stand-ups also provide a forum for everyone to get important face time with one another. As monotonous as stand-ups might seem, if the majority of your team spends a significant portion of its time programming independently, daily stand-ups might be one of the few face-to-face interactions it has.

Note

When I use the words “in-person,” I’m referring to any face-to-face medium. That can be physically in person in the same office or scattered throughout the world and meeting over video conference. The important piece is that everyone is taking the time to see and listen to one another away from distractions.

Other teams prefer an asynchronous way of catching up, relying instead on their main collaboration platform (whether that’s Slack, Discord, or a similar tool) to post a summary of their previous workday. One downside of in-person stand-ups is that they require everyone to be available at precisely the same time every day. For highly distributed teams, in-person stand-ups are either very inconvenient or nearly impossible amid a wide array of time zones. They can also awkwardly break up engineers’ mornings or afternoons and diminish the amount of time they have to focus deeply on a task at hand.

Effectively refactoring code usually takes acute concentration; you are trying to decipher what the current implementation is doing (by reading through it or running the corresponding unit tests) and then, from that understanding, determine the best way to improve it, and then, finally, craft the improved implementation, replicating the precise behavior of the initial solution. Most programmers need several consecutive hours of uninterrupted time to get into the headspace required to make measurable progress toward a difficult task. If an engineer gets into work at nine o’clock only to be interrupted by a stand-up at 10:30, they might not even bother to start on a task, knowing that they won’t make much progress.

Tip

To best simulate a stand-up meeting, asynchronous stand-up usually requires the participants to provide an update by a certain time. Say, for instance, your team provides updates asynchronously by 10:30 a.m. every weekday. If you’re an early bird and typically get in to the office at 8 a.m., you might provide your update immediately and dive headfirst into your next task. Your fellow teammates submit their updates as they begin working. By 10:30 a.m., if anyone on the team hasn’t written anything yet, they might get a gentle nudge from your manager until everyone’s given an update.

You can continue to hold daily stand-ups when working on a large-scale refactor, but you may want to revisit their frequency throughout its execution. For example, if your team has entered a milestone with highly parallelized workstreams, updating one another on these distinct, loosely related streams on a daily basis might not be a good use of time. If your updates are highly technical and detail-oriented, most of your teammates won’t have the granular context needed to appreciate them. Instead of a daily stand-up, you could consider providing more comprehensive updates twice a week or during a weekly sync.

Weekly Syncs

Daily stand-ups are meant to convey a quick snapshot of everyone’s progress; they are not a one-size-fits-all means of regular communication with your team. Think about the half-hour stand-up. If your team members are spending a considerable amount of time discussing at great depth their tasks and the problems they’re solving during the stand-up, you should consider two options. The first is to ask them to continue their discussion after the stand-up; if the conversation does not involve a significant portion of your team, that should work just fine. Your second option is to begin hosting a weekly sync. This forum should give your team more dedicated time to dig into the topics most top of mind for them.

With large refactoring efforts, because the affected surface area can be quite substantial, a range of engineers from across the organization will typically be involved. When the team is highly cross-functional, with not all members devoting 100 percent of their time to the refactor, a weekly sync is usually a better option than a daily stand-up. With a weekly half-hour or one-hour meeting, the team members can focus on discussing only the updates that are pertinent to the refactor.

I would recommend budgeting about an hour for a weekly sync. You can structure a weekly sync as you would a stand-up, with a few tweaks. For the first half of the meeting, have everyone take turns sharing what they’ve accomplished in the refactor over the previous week. If you expected to make more progress, you should hypothesize about why that is: Did you run into roadblocks? Did other, nonrefactor work take center stage? It’s just as important for the team to know what’s holding up the project as it is to know what everyone’s working on. This way, if work needs be redistributed to keep the project moving forward, the team can spot it right away and pivot accordingly. As you go around the room, make note of any topics that folks might want to discuss at greater length.

For the second half of the meeting, take the time to discuss any important topics. You can gather these topics throughout the week and come to the weekly sync with a complete agenda. Maybe, for example, a teammate discovered a new edge case during testing. Although this was probably discussed in a stand-up at some point, you may want to discuss the edge case further during the weekly sync and give the team a chance to amend the rollout approach to make sure similar edge cases are properly handled.

You can also gather discussion topics during everyone’s updates, keeping an ear open for any intriguing subjects. For instance, a teammate might have mentioned spending time prototyping a way to automate the more repetitive portions of the refactor. Others on the team might benefit from learning more about this prototype and how they can leverage it themselves. As always, practice good meeting etiquette and make sure that everyone has an opportunity to share their thoughts.

Strong teams are built through strong connections, and strong connections are built through meaningful in-person interactions. Weekly syncs are the perfect forum for solidifying your relationship with your teammates. Why is building a strong team so important? Having a team that supports one another can be particularly helpful when the going gets tough. For example, if someone on the team ships a change that causes a serious regression, knowing that the team has their back and one or two teammates will be happy to jump in to help resolve the issue can substantially reduce their anxiety and, in the long run, prevent burnout. Being able to show up for one another is also really important when the work starts to drag.

Most large-scale refactors have sizable milestones consisting of tedious, repetitive work. (All of the examples in this book to date have one or two lengthy, monotonous steps.) These milestones tend not to be exceptionally challenging or engaging; they’re dull but necessary. When the team needs to execute these stages, usually the project starts to feel as though it has slowed to a crawl. Teammates can be more prone to burnout during these stages, but having a group of individuals you can lean on, with which you can share your frustrations, can make a world of difference. If someone on the team is having a difficult time finding the energy to continue, maybe someone else with a bit more capacity can step in and lend a helping hand.

Tip

Be certain to take notes during your weekly sync so that you have a record of everything that was discussed (and any conclusions drawn by the team). These notes, combined with the tasks you’ve been tracking in your project management software, will be helpful when you need a quick reference of everything that’s been achieved by the team for your next retrospective.

Weekly syncs can be combined with stand-ups, or replace stand-ups entirely. In my experience, I’ve found that even with daily or twice-a-week stand-ups, having a weekly team sync is incredibly beneficial because it gives everyone an open forum to discuss the week’s most important topics in greater depth. I would especially recommend holding a weekly sync if your team opts for asynchronous stand-ups; this way, everyone has an opportunity to interact in person on a regular basis. Try out different variations of stand-ups (asynchronous or in-person, daily or every other day), combined with a weekly sync, and see what works best for your team.

Retrospectives

Retrospectives are just as beneficial to teams executing on a large-scale refactor as they are to Agile product development teams. They give your team an important opportunity to reflect on the latest iteration cycle, highlight opportunities for improvement, and identify any actions you can take moving forward. Setting time aside to discuss what went well, what could have gone better, and what you plan to change is an essential part of growing a team as a unit and as individuals.

The vast majority of Agile development teams participate in regular retrospectives at different cadences. Some product-focused teams will hold a retrospective (a retro) after the launch of a new feature or after a set number of development cycles. Teams working on longer-term projects might hold a retro once a month or once a quarter. Large, at-scale refactors typically benefit most from retrospectives at the end of major milestones. These are usually lengthy enough to have substantial content to consider, but not so large that the team has trouble remembering everything that’s unfolded since the last retrospective. On occasion, smaller subtasks within a single milestone may feel notable enough to justify a retro of their own; there is no perfect, one-size-fits-all answer for all teams and all refactors. If you’re inclined to think a retrospective is worthwhile, simply ask your team whether it agrees. If it does, schedule one; if it doesn’t, simply wait until the team’s completed the next substantial set of work.

If you aren’t confident in your ability to run a good retrospective, there are plenty of publicly available resources to help you. Atlassian has quite a few articles and blog posts on its website, outlining best practices and exploring original ideas for spicing up your retros.

Outside Your Team

As with any large-scale software project, a fair share of individuals outside your team will have an interest in your progress. This could include upper management, engineers on affected teams, or senior technical leaders. Upper management will want to check in on the project to ensure that the refactor is progressing at the expected pace and producing the expected results. From its perspective, large refactoring efforts can easily turn into money pits: valuable, expensive engineering time is spent rewriting functionality that already exists, and if the project strays, the time and financial investment only increases. There’s also the matter of opportunity cost, as we discussed in Chapter 5, when managers have to weigh the refactor against further feature development. Upper management will want to be reassured regularly that its decision to invest in the refactor was a good one, and if at any point it determines otherwise, it will likely hatch plans for either pausing or stopping the refactor altogether. You can make sure that it continues to support your effort by honing your communication skills when providing updates outside of your team.

Managers and engineers on teams affected by the refactor will want to keep track of each stage of the project to gauge when they risk bearing its effects. They’ll want to know precisely when the team expects to roll out relevant changes and how long it anticipates it will take. Meanwhile, senior technical leaders will be on the lookout for any setbacks as an opportunity to help steer the project back in the right direction. Typically, these individuals play an important role in shaping the company’s technical vision and are responsible for ensuring that complex, important technical endeavors succeed, including any large-scale refactors.

In this section, we’ll discuss how you can ensure that all your external stakeholders stay up to date with the latest progress on your refactor. We’ll first look at some work you can do upfront to set good habits early, and then we’ll look at how you can keep up with external communication throughout the project’s execution.

When Kicking Off the Project

There are some important preliminary decisions you’ll want to make about how you plan to communicate with your external stakeholders when you kick off your refactor. By making these decisions early, you’ll help your team save valuable time when coordinating with colleagues outside of your team and decrease the overall likelihood of any miscommunication with external parties.

Choosing a single source of truth

Even the smallest companies use a number of tools for the same set of tasks. Your company might use both GSuite and Office 365, with some departments preferring one product over another. Even within your own engineering organization, you may have documents speckled across GSuite, GitHub, and an internal wiki. As someone searching for information about a product feature or in-flight project, having to search half a dozen platforms for disjointed pieces of information is aggravating. It can be even more frustrating when pertinent information is in more than one location, and the information doesn’t agree.

When you kick off your refactor, choose a platform your team enjoys using to collect all documentation related to the project. Because you’ll be regularly creating new documents and updating existing ones, you’ll want to choose the solution that has all your favorite bells and whistles. If you’re annoyed every time you need to add something new, you’ll be less likely to do it, and the documentation will fall out of date.

Within your chosen platform, create a directory to house all pertinent documentation; this will serve as your single source of truth. Documentation can include technical design specifications, the execution plan you developed in Chapter 4, meeting notes, postmortems, and so on. Wherever other engineers look for documentation, either link to your directory or, better yet, link to a specific document within it. If your colleagues have muscle memory from searching GitHub for technical documentation but you prefer writing in Notion, create an entry for your documentation in GitHub and link it directly to your Notion entry. This way, not only will your documentation be easy to find, you’ll be certain that there aren’t any outdated copies floating around.

As your team generates documentation throughout the execution of the project, make sure that it all lands in your project directory (with updated external links from other widely used document sources).

Setting expectations

Next, you’ll want to set expectations with external stakeholders. Many of these stakeholders will regularly check in with you, polling for new information. Unfortunately, this model can become quite bothersome the more stakeholders you have. If you or your manager receives an email or message every time someone in upper management has a question about how the refactor is progressing, before long, you’ll end up spending quite a bit of time answering these requests. On the other hand, there may be some stakeholders that you wish would check in periodically but unfortunately do not. When this is the case, your team must push information out. Consistently needing to propagate information proactively out to numerous stakeholders can get irritating, particularly if the receiving party doesn’t acknowledge that they’ve read the information you provided.

Instead of either answering each request or contacting each stakeholder individually, spend some time determining how you intend to communicate progress and setting up expectations with your stakeholders early about where and with what frequency they should expect these communications. When stakeholders break from the patterns you’ve established (e.g., you get a ping from your skip-level), instead of providing the information directly, simply reply with a gentle reminder of where they can find what they need.

When you kick off the refactor, take some time to draft a rough communication plan. This plan should include information about the following:

Where stakeholders can find information about the current stage of the refactor

There are a number of places where you can make this information easily accessible to external parties. If your team uses Slack, you can create a channel to house conversations pertinent to the refactor and set the channel’s topic to a short description of the current stage of the project. At the end of the week, post a weekly round-up message detailing the progress made over the past few days. (If you hold weekly sync meetings, you can draft this message immediately afterward and link to your meeting notes.) If your team uses JIRA, provide a link to the project board. For stakeholders who need regular, high-level updates, consider adding a summary field that the team updates weekly on the top-level project.

Where stakeholders can find a high-level project timeline

You can include a high-level project timeline at the root of your project documentation directory, directly within the communication plan itself, or as a subsection to your execution plan. Make sure to keep this timeline updated if any dates end up shifting as the project progresses.

Where engineers can expect to find technical information about the refactor

Here, you can link to the directory where your team intends to draft documentation related to the refactor. Provide a short summary of the kinds of documents the team plans to aggregate there.

Where stakeholders can ask questions

There will be instances when individuals across the company will either not be able to find the information they need in the provided resources, or prefer asking the question directly rather than locate the information for themselves. When that happens, you’ll want to make sure that they know where to go. If your team uses Discord, either direct them to the project channel or set up a channel exclusively for questions. If your team relies on email and it has an email group, have the members send an email to the team as a whole rather than to an individual. If your team is cross-functional, set up an email group for everyone involved and direct questions to that group.

When affected teams should expect to hear from you

When coordinating with teams that risk being affected by the refactor, you want to maintain a high level of transparency. You want to make sure that no one on these teams is surprised or set back by the work your group is doing. To make sure that everyone is on the same page, provide a list of guidelines you intend to follow when interacting with other teams’ code. This could include tagging one or more individuals from that team for code review when modifying code for which their team is responsible or attending their stand-up to provide updates on the refactor when pertinent to their team.

During Project Execution

There are a few communication habits your team should consider adopting during the project’s execution. These strategies can help everyone at the company stay informed of your progress while minimizing the amount of proactive outward communication your team needs to do. We’ll also discuss how best to engage with engineers external to the team when seeking out their expertise about the project.

Progress announcements

Progress announcements are not only important to let everyone know that you’ve completed another milestone (and unlocked any number of benefits as a result), they are also crucial in continuing to make your team feel productive and boost their morale. Large-scale refactors can feel daunting for teams, even for teams accustomed to working on lengthy projects. Celebrating each milestone as it wraps up helps everyone feel a sense of achievement throughout the duration of the project.

However your company announces the launch of new features, whether that’s a department-wide email or a message in a Slack channel, inquire about providing important progress updates for the refactor. Your team will get important recognition for their hard work and demonstrate to a wide audience that refactoring is a valued engineering investment.

Execution plan

In Chapter 4, we learned how to draft an effective execution plan for our large-scale refactor. We can go beyond using this plan as a simple road map and use it as a place to document our work throughout the project’s progression. Make a copy of the original execution plan. The original version should remain relatively untouched beyond light updates to estimates and milestone metrics as necessary. The copy will serve as a living version of the original document and should be progressively updated as the project develops. (Enabling version history will give you the ability to easily go back in time and compare your initial values with your latest updates.) This could include anything from strange bugs encountered, unexpected edge cases uncovered, or diversions in the plan. This second version of your original execution plan should give any stakeholders a much more nuanced view into your progress and help your team keep better track of the work it has achieved to date.

For instance, in our example from Chapter 4, the software team at Smart DNA was tasked with migrating all Python 2.6 environments to Python 2.7. We’ve copied over the first milestone of the team’s execution plan as follows:

  • Create a single requirements.txt file.

    • Metric: Number of distinct lists of dependencies; Start: 3; Goal: 1

    • Estimate: 2–3 weeks

    • Subtasks:

      • Enumerate all packages used across each of the repositories.

      • Audit all packages and narrow list to only required packages with corresponding versions.

      • Identify which version each package should be upgraded to in Python 2.7.

As the software team begins making progress on the migration, it might start filling in the copy of its original plan with more context on its findings. We can see some of those additional details in the plan that follows:

  • Create a single requirements.txt file.

    • Metric: Number of distinct lists of dependencies; Start: 3; Goal: 1

    • Estimate: 2–3 weeks

    • Subtasks:

      • Enumerate all packages used across each of the repositories. When we started combing through all of the packages used by the first of the three repositories, we were surprised that the code relied on six additional dependencies that weren’t explicitly listed in the respective requirements.txt file. The researchers were able to provide an updated list for the first repository as well as in the 10 other dependencies missing from the requirements.txt files for the other two repos.

      • Audit all packages and narrow list to only required packages with corresponding versions. Thankfully, 80 percent of the packages used by the three repos were the same. Of that set, only eight of those packages had different versions that needed to be reconciled.

      • Identify which version each package should be upgraded to in Python 2.7. This was tricky for seven of the packages in the final, combined set. For these packages, their 2.7-compatible versions deprecated a number of APIs and features that the researchers actively used in two of the three repos. We worked with the research team to gradually migrate away from using these deprecated features before continuing with the refactor.

Updating the execution plan as you go means that others can reference it throughout the project’s lifetime to get more context on the specific work the team is doing during each of its many stages. Any SMEs joining the project at a later milestone (or any new teammates being onboarded partway through the refactor) can ramp up on everything the team’s worked on to date just by reading through the execution plan. If you’re anything like me, sometimes you forget why you made a certain decision several months ago; by keeping a verbose account of everything you’ve encountered and the conclusions you’ve reached along the way, you can easily go back and remind yourself of precisely what happened and why.

A detailed account of the team’s experience can also be helpful for engineers and managers referencing the refactor well after it’s completed. Engineers seeking to understand how the codebase has evolved over time may want to read your detailed plan. For the engineers involved with your refactor seeking a promotion, having concrete documentation pointing to the highly technical problems they solved at each step can be incredibly valuable. Elsewhere at the company, engineers looking to kick off their own large-scale refactor might look to your documentation for an example of how to execute a substantial refactor successfully.

Seeking feeback from senior engineers

All of us seek advice from peers and experienced colleagues when solving difficult problems. While we might be eager to request feedback from senior engineering leaders (and benefit greatly from it), getting and retaining their attention can be notably difficult. Whether they’ve been engaged with the refactor from day one as SMEs (see Chapter 6), or are just getting up to speed, they’ll likely be slower to respond to your inquiries simply because they are unusually busy with many responsibilities across a multitude of projects. Ideally, if you are able to communicate your expectations appropriately, none of these individuals should become bottlenecks.

Note

The term “senior engineer” here refers to the most experienced individual contributors within a team, department, or company at large, not to be confused with the title, Senior Engineer, held by many professionals in the industry. These are usually the folks with much bigger titles like Senior Staff, Principle, or Distinguished Engineer. Sometimes, these are simply the folks who have been at the company the longest.

When soliciting feedback from these senior engineer leaders, we must first decide the scope of the feedback we’re looking for. This is helpful for two main reasons. First, explicitly defining which aspects of the problem or solution we want our colleague to evaluate ensures that we won’t get unexpected, frustrating feedback on pieces we’ve already nailed down. Second, they’ll be able to focus immediately on just the essential pieces, saving them a great deal of time and energy they would have otherwise spent assessing a much greater problem.

Next, we have to determine how crucial their feedback is to the momentum of the project; that is, can you continue to make progress without their input? If you believe you can continue to make progress without their opinion, be explicit about it. This way, the engineer can properly prioritize giving you the feedback you need against similar requests they might be juggling from other engineers across the company. If you believe their input is required for your team to continue making progress, letting them know that they are now a blocker should give them adequate urgency to get back to you quickly. Regardless of the urgency, you should set some clear expectations for when you need their feedback by so that no one is left twiddling their thumbs.

Tip

If you’ve let a senior engineer know that their insights are a blocker, set expectations for when you’d like to have heard from them, and if you are still waiting for a reply, it’s time to get assertive. If their calendar isn’t flooded with meetings, book some time with them one on one to discuss the item at hand. (Be certain that your meeting description has all the pertinent details!) If you just need a few minutes of their time, try stopping by their desk and seeing whether they’re available to chat, or catch them on their way out of a meeting. It’s much more difficult to put off talking to someone when you’re face to face.

We also need to consider how crucial the senior engineer leader believes their own feedback is to the momentum of the project. If you both agree that their input is not a blocker, great! But if there’s a chance that they’ll be surprised and disgruntled if you move forward without taking their opinion into consideration, you need to be aware of it so that everyone’s expectations are properly aligned.

To illustrate this in action, let’s say you’re working on a prototype for a new library you’re building as part of a large refactor. Your prototype defines some basic interfaces, with a handful of temporary, incomplete implementations. You put up your changes for code review, complete with a short description and links to a design document your team developed. You want some feedback from a senior engineer, so you tag them and a few other teammates for review. Unfortunately, you forget to tell the senior engineer that you’re looking for feedback on the interfaces (not the implementations) and are hoping to merge these changes within the next week.

A few days pass with comments from your teammates but nothing from the senior engineer. You send them a message asking whether they’ve had a chance to take a look at the code review. They assure you that they saw the request and that they intend to get to it by the end of the week. After some back and forth with your teammates, you decide to merge the prototype and continue iterating on it in subsequent code reviews.

A day later, the senior engineer opens up your code review and begins to read through it. They immediately begin commenting on the implementation details, becoming increasingly alarmed as they realize that the code has already been merged. Now everyone’s irritated: you’re irritated that the senior engineer took too long to review your changes and ultimately focused on the wrong aspect of the code; they’re irritated that they left comments on what turned out to be temporary code and that you’ve merged your changes without waiting for their input. All of the disappointment and miscommunication could have been avoided had the right expectations been set from the start.

Always Iterate

If there’s only one thing you take away from this chapter, it should be this: there is no single correct communication strategy. Every refactor needs different communication strategies, and these strategies can change throughout the lifetime of the project. The habits you establish should be molded by each of the facets that makes the refactor unique: the team you’ve gathered, the engineering groups affected by the changes, and the level of involvement of external stakeholders.

If at any point you find that your habits are no longer serving you well, shake things up! In the best case, great communication habits can keep your team working effectively at a sustainable, steady pace. In the worst case, bad communication habits can hold your team back and actively prevent the project from moving forward. If something isn’t working, you’re much better off attempting to change it than sticking with habits that could slow you down.

Our next chapter continues with the theme of establishing patterns that help you and your team execute in a productive way. We’ll highlight an assortment of ideas (both technical and nontechnical) your team might want to try throughout the refactor’s development.