In December 2016, a front-end developer left a team where I work. Apart from other changes, this created an issue. When he was working, the project had a couple of complex modules we were developing with him together. When he left, I realized that only I am able to work with them – other two team members knew nothing about how these modules function. This is called “exclusive code ownership”, and it’s bad in the long term, so I had to start fixing this. Here’s why it’s bad and what to do with it.
Imagine there’s a complex module in your project that only you work with, and you’re hit by a bus tomorrow. Will the team be able to continue developing this module the next day? Most likely no. This means the bus factor of your team is 1 – that is, it’s enough to
kill remove a single developer from the project to severely slow or even stop its development.
Until recently, our project has been heavily relying on a custom front-end framework that was developed by only a single team member. No other developers knew its inner parts, and only a couple of them knew it deep enough. This meant the bus factor of the whole front-end team was just one. This, along with other issues, led us to migrate from this custom framework to React in 2016.
If there’s a module in the project that you exclusively own, then, regardless of the team size, only you will be able to make changes in it. If tomorrow you receive 5 critical issues related to this part, there’ll be nobody to help you. You may even slow down your team if these critical issues block them.
We had this problem when a part of our front-end infrastructure changed, and this broke builds for the whole team. Because it was only me who knew how all this stuff works, I had to fix the problems one-by-one. If other team members knew this, they could’ve helped me bring everything back sooner.
Leaving is hard#
If once you decide to leave the project, you’ll have to transfer all your unique knowledge about how these parts work to other team members. Depending on the knowledge size, this can take significant time, and it still will be less effective than if other members had real experience with the code.
You create risk and slow down delivery
What to do#
Documentation and maintainability#
You have probably heard this advice for a lot of times, but it’s never bad to repeat it again. Make your code documented and maintainable. This includes code cleanliness, inline comments, and external documentation.
It’s your choice how much to document the code. I usually try to make it self-documenting and add comments only if the purpose of the code or the decisions behind it are still unclear. Also, remember that self-documenting code is better than comments, and comments are better than external documentation. People occasionally forget to update the comments and often forget to update the external documentation, so the only up-to-date source of information is code.
In my experience, writing detailed commit messages is very underestimated. I’m sure that one of the best ways to share your code knowledge is to include it into your commits. Once you commit something, it stays in the history forever, and tools like git blame help you to easily find which commit changed the specific lines. This means that even if you leave the project, the other developer that will work with the piece you’ve written will be able to git blame the code and see why you made this or that change.
What to write in a good commit message? Well, this is one of the examples from my project I like (I wrote this so I like it, pretty obvious):
Look, this commit includes:
The last part is exactly where you put your code knowledge. Answer why you did the changes. Explain the background that could be unclear to another developer in the half of the year. Document the limitations that your solution has and the issues it creates (if any). Include everything else that you consider significant.
Follow to this Caleb Thompson’s article if you want to read more about good commit messages (especially, take a look at point 4). Also, kudos to Andrey Listochkin for giving the advice about this in one of his talks.
If you’re a team lead, and you realize that you have this problem in your team, you can use your power to change this:
- Find what modules are exclusively owned by someone.
- Find what tasks you can give to other team members so that they get experience with these modules.
- Ask the module owner to introduce developers that will work with the tasks into the module code.
If you’re a regular developer, and you realize your team has this problem, talk with your team lead. Feel free to show them this article.
Also, this should be solved by introducing mandatory code review or pair programming, though we haven’t practiced this ourselves.
Docs, commit messages, processes
So, well, the checklist:
- Write self-documenting code
Use comments when it’s necessary
Write good commit messages answering “why”, not only “what”
Involve other team members into working with the code
Follow me on Twitter: @iamakulov