While communication can be difficult in any work arena, communication between developers has unique challenges.
These challenges often center around the nature of the work we’re doing, resulting in asynchronous communication, and issues around how "it works on my machine".
Communication between members of partially or completely remote development teams tends to be asynchronous. Developers communicate with each other across the globe, using a variety of platforms like slack, discord, and email. Frustrations can arise, for example, as developers try to communicate across time zones and potentially even language barriers to resolve development issues with colleagues who aren’t even awake.
Then there is the pesky "it works on my machine" issue. When a developer creates a new feature, it doesn’t always work on a colleague’s - or worse, a customer's - device. This often occurs due to missing or incorrect environment variables such as databases credentials, or differing operating systems and/or browsers.
Trying to discover why someone else's code is not working on your machine can be tough, because you don't know how they got it to work, and what information they need about your machine to debug. Finding a solution in these scenarios requires ongoing back-and-forth communication that potentially becomes very frustrating.
No tool magically fixes communication challenges. Good results come when we cultivate empathy and develop processes to reduce friction. For good developer communication, here’s a simple formula:
Assume the best about the other person
Most people are just trying to do their best and developers really want their code to work for others. Yet it can be easy to become angry when you assume, for example, that another developer is being intentionally vague when your attempt to communicate with them to fix a problem isn’t working.
When communication is difficult, it’s best to take a step back and give the other person the benefit of the doubt. Ask yourself if it is possible that you’re the one not communicating clearly? Perhaps you can fix something too. In any event, choose to believe that others are doing their best to communicate effectively with you.
First understand, then be understood
When reviewing another developer’s work or trying to run their program, ask yourself these questions:
Did you read their instructions carefully? Did you follow each step? Did they leave any comments in their code, or anywhere else that might be useful?
In the best case scenario, you can solve the communication on your own by making sure you've understood and tried the other developer’s instructions. Alternatively, you may still have issues, but your next conversation with the developer builds on what you discovered on your own. When you do everything you can to understand, you show the other developer that you're not being lazy or difficult, but are working towards clear communication.
Show your work
If you are sharing your development work, have you written your steps out? Do you have an updated README? Have you added comments to your code/PR?
If you're reviewing someone’s code, have a question, or have spotted a bug, have you explained the steps it took to produce the issues you see? Can you share a screenshot or recording?
There are tools and processes you can use to show your work, and make it easier to communicate with other developers. As a best practice to enhance communication efforts between developers, your team or company should acquire the appropriate tool and write down a process to help developers show their work. For example, if your company uses BugReplay, you can capture screenshots coupled with console and network logs to show your outcomes to another developer.
Let’s walk through a couple of “It works on my machine” communication scenarios, where two developers learn to use the formula above to communicate clearly and effectively with each other.
In this scenario, Sally is a developer working on the authentication workflow for a new website, where users are authenticated via their Google accounts. She’s asked Bill to review her work. Feel free to check out the source code, or take a look at the live demo.
Sally just completed programming the ability to authenticate users with their Google accounts. She asks Bill to pull her code base and test whether he can log in. She sends him a link to the repository, provides the environment variables he needs to put in his .env file, and tells him the instructions are in the README.md file.
Bill clones Sally’s repo, installs all the packages, and sets up the variables correctly, but once he clicks the "Continue with Google" button, something goes wrong! He's not sure why things aren't working – he checks his .env file to make sure the setup is correct, then runs through the installation steps again.
He still gets the same error. Bill figures the best way to share what seems like a bug is to send Sally a screencast of the issue. You can see for yourself his recording in BugReplay, which captures helpful network logs and other information about the environment in which the failure occurred.
When she reviews the logs, Sally sees that Bill ran the code on the port https://localhost:8000. However, the Google authentication is set up so that it redirects to https://localhost:3000. When she contacts Bill to ask why he ran the code on port 8000, he tells her he was told to do so in a previous project, and assumed he should do so again.
Sally explains that Google requires allowed domains to be explicitly set up, and the developer domain they are using is https://localhost:3000. Bill reruns the installation, this time without overriding the default port 3000, and it works like a charm! Sally updates the README to make the domain requirement more explicit so others won’t experience Bill’s issue.
Now let’s review how Sally and Bill applied the communication formula to their situation:
In the end, this was a communication win for everyone!
In this scenario, Sally implements a new passwordless authentication method using 🪄magic🪄 links. Unlike Google authentication, magic links can be used for preview deployments.
As a result, when Sally asks Bill to test her new authentication method, he won’t have to pull all of Sally's code, install the dependencies, and run everything locally on his machine. Sally uses the platform vercel so that each pull request automatically deploys its own unique URL for every commit which anyone can view.
Sally sends Bill a link to her pull request, which directs him to this preview deployment.
Bill is happy to review Sally's work, but again runs into trouble. As before, he documents his attempt to test Sally’s authentication method and sends the recording to Sally.
In the recording, as shown in the video below, Bill repeatedly clicks the Continue with Email button, but nothing happens:
From the network logs Bill sends her, Sally sees that Bill gets a 500 HTTP response code, which indicates a problem on the server. She tests the preview link herself and gets exactly the same result.
After some additional investigation, Sally realizes that she forgot to add the necessary environment variables to production 🤦. She adds the variables and sends Bill the deployment preview again. This time Bill reviews and approves!
Sally and Bill have certainly become better at applying the communication formula, as you see here:
Just as we have to learn how to code, we also need to grow our communication skills.
Acquiring communication skills isn’t hard when we follow the communication formula to become more empathetic, aware, and diligent.
In the end, while understanding linked-lists can help you get a job, effective communication allows you to excel on the job.
