Collaborating with the future: How to leave a lasting impression

By Richard

Screen showing the message 'Do what is great'.

As people involved in software projects, we must be mindful of team members that we will be collaborating with through the code we leave behind. When fellow contributors join our project we want the experience to be as smooth as possible. This isn’t just for the sake of the developers. It is also for the Product Owner, who has invested a lot of their time and money in the project.

It’s hard for developers to deliver value after they have been dumped into the deep end of legacy projects. It’s also unreasonable to expect an often non-technical Product Owner to know the reasons for all of the technical decisions.

Documentation for collaboration: Quality counts

Documentation is one solution to these issues. While documentation matters, it’s the quality not the quantity that counts. From experience it doesn’t take long for the documentation and the software to diverge. Misleading and incorrect documentation is just as bad as none at all.

Divergent codebase from lack of collaborating — *When collaborating in a shared space you need clear documentation to avoid confusion*

As time passes and projects grow, team dynamics change and the subtleties of a project will be lost. The context that goes into making design decisions is often as important as the code itself. Without context, codebases will cause problems for future team members that could have been avoided.

We see this every day and it is important to acknowledge that it is a normal part of software development. Coding practices and the tools available can drastically change in a short space of time. Just as the backgrounds and experiences of the people who are collaborating on a piece of software will. Context and domain knowledge are the easiest thing for people to lose and often the most overlooked. Documenting the key business requirements behind your code is a good way of making sure you don’t lose context when people leave.

With this in mind, it’s very important you have a pragmatic approach to writing and updating your documentation. Once you have spent time fixing or developing a feature, you’re in the best position to improve tests and documentation. By keeping this a priority, you will save another developer from having to go through the same learning process again. This could even be a future you!

Clean code left behind for future collaboration — *Clean code left behind for future collaborators*

Code reviews and communication: How collaborating well now helps future work

It’s important to leave behind code that is written with a clear intent and will make sense to future readers. The most difficult pieces of code to work on are not necessarily the most complex. Instead they can be the areas with the least documentation or consideration of future developers.

Steps that can help mitigate this can be as simple as:

Regular code reviews
Open discussions with team members
Updating documentation as you go
Descriptive naming

Having regular code reviews helps to keep everyone in your team on the same page with features that are being developed. This is just as important as maintaining code quality. It will help to make sure that all of the workings of your system are not in the brain of one person.

Code reviews are also great for helping your team communicate with each other. When the team knows about each others strengths and weakness, they are in a better position to have open discussions. When a team can communicate well, they can also hold each other accountable for things like updating documentation.

Documentation can often feel like an afterthought or just ‘something that needs to be done’. If you update it in small pieces as parts change, it will be much easier to maintain. Having good naming conventions can really help with this, as you don’t have to try and match something vague in the codebase with its real world partner.

Summary

Don’t overlook your documentation. It is extremely important to maintain a solid understanding of how various parts of your system work, and it is much easier to write and update while the content is fresh in your mind. Trying to reverse engineer tests and documentation is very difficult, especially if it is for a project that you or members of your team are still learning about.

Always keep in mind that when you are contributing to a project, you are not only collaborating with the people who are currently working on it, but you are also collaborating with any future people who join the project. I hope these tips will help to improve your collaborating practices, they may even help you work with a future you.