Why discussions about your code must live with your code
The established process for software development in a team setting is a variation on this:
- Get together in the beginning of the week and lay out the sprint.
- Get your work done without becoming an annoyance to your team members.
- Get together at the end of the week after you commit your code and hope it’s good enough.
The work gets done. Rinse. Repeat.
So we posit a hypothesis: Developers don’t ask enough questions and don’t communicate nearly enough about code. As a result, they don’t consult early enough with their team members and commit sub-optimal code.
As veterans in software development, we have experienced this situation ourselves and recognize the process and its potential pitfalls. So why do developers communicate less than they should? Why do they shy away from asking questions?
Some reasons are cultural. If you ask a question, you might be seen as not being able to figure it out yourself. Rather that being seen as sharing knowledge, and preempting future problems, developers fear being seen as a burden, or as incapable of solving their own problems.
Agile also plays a role in reducing the amount of written communication, while elevating face-to-face communication to preferred status. This is how the Agile Manifesto demotes other forms of communication: “The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.” That might be true when a team is sitting in the same room all of the time. But most teams these days are remote at least part of the time, and many are increasingly working in different time zones across the globe. Clearly, written communication becomes a necessity when teams are either large or remote.
Team chat is now the primary way in which development teams communicate in writing. While there are many advantages to using Slack or MS Teams over other communication tools such as email, it suffers from three significant problems when it comes to software development teams.
1. If you want to discuss code in Slack, for instance, you need to copy and paste code blocks which strips essential information requiring you to recreate all the context that explains the code. That can take as many as 18 steps to accomplish. Therefore, it does not happen very often, because it’s just too hard to do frequently.
2. The second problem is that while you might get the answer from a team member using this method, you are not likely to ever find this conversation again. Slack and other general team chat solutions are just not designed to make retrieving this type of information easy and convenient. Therefore, if you are looking for this conversation six months or a year from now, you will almost certainly not find it.
3. Finally, this type of communication does not lead to shared knowledge that becomes accessible. As you have your discussion with some of the team members, others will never see it, and new developers will certainly not come across it.
The best solution to this communication challenge is to move team chat into your favorite IDE and make code blocks first-class objects within the conversation stream. This way, your team chat becomes code-aware. Then, by attaching the conversations to the code itself in an accessible but unobtrusive way, the code becomes self-documenting and the whole team benefits from every interaction. As a result, less time is wasted, technical debt is reduced, code quality is improved, and everybody feels like they are working on meaningful tasks.