If you were asked to list the essential tools in your remote team’s stack you list would likely list: 

• A Source Code Manager such as GitHub, GitLab, or Bitbucket
• An Issue, Task, or task management Tool like Jira or Trello
• IDEs
• Some kind of code review tool, which could just be Version Control System.
  

Perhaps the most important tool though is your Code Discussion tool.  Your team likely uses collaboration software such as Slack, MS Teams or video conferencing tools such as Zoom or Skype. Those are all general-purpose, though. They are not just for developers… the marketing team, accountants, HR...everyone in the company uses them. They also aren’t designed specifically for discussing code. 

Before getting into some specifics for why remote teams need a code discussion tool let’s highlight a couple of traits of code discussion tools that differentiate them from more generic communications tools such as Slack.

a) You can discuss code in your IDE

‍
You write code in your IDE. You think about code in your IDE. But where do you discuss code? Leaving the developer-friendly confines of your editor to ask a quick question or share a thought requires an inefficient context-switch resulting in one of two outcomes. Either you risk leaving the development mindset due to the need to switch windows, navigate channels, copy-paste code, and perhaps getting lost reviewing what other unread messages you have. Or you stay heads down and don’t bother asking the question. (See Three Communication Problems Solved by Moving Chat into your IDE for more on this.) The ability to discuss code should be integrated in your development environment.

‍

b) Discussion about code is attached and permanently saved with the code.

When a comment is added to a pull request it is attached to that pull request forever. When a comment or reply is added to a Jira ticket or Trello card it remains attached to that ticket or card. Conversations about code taking place in general purpose communication tools? They are pretty much lost forever. A code discussion tool treats the code being discussed as the first-class object, and saves the discussion about code along-side it.

These components of a code discussion tools benefit every development team but are especially important for distributed development teams, whether fully distributed or just a handful of remote developers. Here are five reasons why remote teams need a dedicated code discussion tool.

#1 - Encourage Passive Knowledge Transfer

In the 2019 State of Software Development survey by Coding Sans developers responded that sharing knowledge is their biggest challenge. It’s often underestimated how much knowledge gets shared passively just by being in the same physical location with team members that are working on the same code base. Consider one teammate yelling a question across the room. Or a conversation resumed at the proverbial water-cooler or coffee machine. Four or five of you grabbing lunch with two discussing some challenge they’re in the midst of. One doesn’t need to be a primary participant in a discussion to gain insight and knowledge from that discussion.

The above scenarios just don’t exist for the remote worker. Instead of a side discussion at lunch you maybe have a Direct Message exchange over Slack or an ad-hoc one-on-one video conference. While the principals in that discussion may exchange some knowledge, nobody else benefits from it. At all. Or worse, as discussed above the overhead involved in initiating a video conference or direct message discussion, relative to just shouting across the room or tapping someone’s shoulder, inhibits the discussion from even happening.

A code discussion tool not only removes the  friction involved in initiating a discussion, but features such as an “activity feed” that allow anyone to review their team’s discussions can serve as a proxy for that water cooler, allowing others on the team to “eavesdrop” at their leisure on any one-on-one or side conversations. 

#2 - Insure Against Developer Turnover  

When a developer leaves your team does knowledge about your code base leave with them?  Yes, of course. The real question is “how much knowledge?”  While it is in the interest of any development team to minimize the knowledge loss, this concern is especially important for distributed development teams that have remote developers somewhere off on their own... by definition. 

An easy fix that materially reduces the loss of knowledge due to developer turnover is the use of  a code discussion tool that saves the day-to-day discussions that occur between developers about code right next to the code.  Passive knowledge transfer just doesn’t exist among remote developers, and conversations happening in general purpose team chat applications like Slack and MS Teams, whether in public channels or direct messages, become lost or forgotten since they are removed from the code, where they can be useful to others in the future.

#3- Facilitate On-Boarding New Developers

Covered above was knowledge sharing between active teammates and preserving knowledge from teammates that leave. Let’s close the loop and consider getting new developers up to speed. 

Developers don’t discuss code with their teammates often enough, case in point sharing knowledge being considered the #1 challenge teams face.  There are a few reasons for this.

1. Without a dedicated code discussion tool, discussing code is cumbersome. 
2. Developer Culture. We all consider ourselves or at least aspire to be that “rockstar” developer which leads to the avoidance of asking questions for fear of looking stupid.
3. Respect of flow state. Development is hard and we all know what it’s like to get into a great flow state, focus, mindset and hence. We don’t want to risk getting out of that state to ask a question, and we don’t want to be a nuisance and interrupt a teammate that may be in such a deep state themselves.
   

While the first reason above applies to everyone, consider which cohort of your teammates are most likely to be affected by the second and third reasons above.  The newbie.  A new, unproven developer on your team most likely wants to make a great first impression, not appear clueless, and be most reluctant to annoy others by interrupting them.

One of the things a code discussion tool does is make discussing code easier. Let’s change gears for a minute and consider how changes in the ease and accessibility of taking a photograph impacted how many photos were taken. In 2000 Kodak announced that consumers around the world had taken 80 billion photos, setting a new all-time record.  Thanks to digital cameras and smartphones about 1.2 trillion photos were taken in 2017. 

One can only speculate as to how much more often developers would discuss code if it was easier and more accessible, but one can unequivocally say a code discussion tool will increase code discussion among team members and with that, it has the potential to change the isolation and limited knowledge sharing in developer culture. Within days,  a new hire can witness a team regularly discussing code, collaborating, and asking questions. In this kind of environment, everyone would be less likely to avoid asking for help.

Another direct benefit of a code discussion tool as it pertains to onboarding is that prior discussions about code are saved directly alongside the code blocks they refer to. Rather than each new developer to the team asking the same question about the same tricky or problematic function, the question will get asked once and be documented right where it’s needed. Potential questions answered instantly this way not only avoid the need to risk interrupting others for help, but they also keep the developer with the question herself in a flow state.

#4 - Reduce Time Spent in Meetings

Meetings can be considered a necessary evil by any development team. Besides the fact that the time spent in a meeting is not spent coding, you also need to consider the cost of the interruption. We touched upon flow state a little earlier and one study found that it takes on average 23 minutes to get back to a task after an interruption. That 23 minutes means that even a quick 15-minute stand-up can easily be an almost 40 minute loss of developer productivity.  Then there’s that awkward dead piece-meal time before or between meetings.  Your 1pm meeting ends at 1:45pm and you have a 2:00pm.  You have 15 minutes free but kinwing it takes 23 minutes to get back to what you were working on how productive are you going to be? 

For a distributed team, both the “necessary” and the “evil” are exacerbated. With remote workers here and there, often spread across incompatible or at least inconvenient time zones, meetings are relied upon more to “keep everyone in the loop.”   What might be a quick 5 minute ad-hoc “water-cooler” conversation for two employees in the same office, becomes a coordinated color-coded, planned interruption block on your calendar.  Five minutes after you respond “yes” to the “Hey, are you free at 2pm to discuss…?” direct message, you’ll get an emailed calendar invite.

One type of meeting is a scheduled or ad-hoc discussion for code review. Code discussion tools, by making it easier and more accessible to discuss code, lead to more issues getting resolved earlier in the process. Some development teams have reported that the increased discussion has reduced the time spent in actual code reviews in half. 

#5 - Code Quality

While there’s no standard definition of “code quality”, a common theme is that quality code is easy to understand. Cleverti suggests that a key component of code quality is “Readability, consistency — how easy it is to read and understand sections of the code; this includes code clarity, simplicity, and documentation.”   

Coding Sans includes among a broader list of quality attributes the following:

Clarity: Easy to read and oversee for anyone who isn’t the creator of the code. If it’s easy to understand, it’s much easier to maintain and extend the code. Not just computers, but also humans need to understand it.

Maintainable: high-quality code isn’t overly complicated. Anyone working with the code has to understand the whole context of the code if they want to make any changes.

Documented: The best thing is when the code is self-explaining, but it’s always recommended to add comments to the code to explain its role and functions. It makes it much easier for anyone who didn’t take part in writing the code to understand and maintain it.

The magic of a good code discussion tool is that it can improve the quality of your codebase by improving all of these attributes in a way that doesn’t require adding any new process, procedures, nor meetings into the mix. Your team’s discussion implicitly becomes quality-improving documentation.  Areas of your codebase that may, for a host of reasons, be harder to understand will inevitably be annotated with explanations of how they work. Then consider the discussions that aren’t happening today because discussing code without a code discussion tool is too tedious. Making it easier to discuss code means that code that isn’t easily understood will more likely be discussed and improved upon...and documented.

Let’s also consider code review. One of the best ways to ensure that code is well written - clear, maintainable, well-documented - is to ensure that it is reviewed by others. In fact, for 4 years in a row “Code Review” was considered the #1 thing a software development team can do to improve code quality as per SmartBear’s annual survey.

As discussed above, a code discussion tool allows more code to be reviewed earlier in the development process as it’s being written..

-----

Above are 5 good reasons your remote team should be using a code discussion tool such as CodeStream. If your team is currently using a code discussion tool we’re sure you may have experienced some other benefits. Please let us know @teamcodestream on Twitter.  We’d also love to hear about what other types of tools you find beneficial for remote team management.