Remote teams: How to build a shared understanding of codebase & architecture?

Question

Situation:

There's a remote team of 6 developers in 4 different countries. It uses CI, version control, Slack and has a weekly status call. They do code reviews on each pull request (always same reviewer). However there are no formal rules on code organization, style and layout. Some of the team members work part-time, so a daily standup is not an option.

The problem:

Knowledge about features being developed is 'siloed' - each developer is generally aware about an isolated part of the codebase he's working on. Tasks are defined in an issue tracker and team discusses what each developer does on the weekly call. However, the features are complex in nature and it's hard to really understand what's going on without looking at code. As a result, the team found that some functionality is duplicated 3-4 times. Since different developers have different coding styles (e.g. how much inheritance depth is ok, line length and so on), some features are hard to maintain and codebase evolution is being pulled in orthogonal directions.

The question:

What are some specific procedures this team can implement, so that there's a shared understanding of the codebase and architecture?

Answer 1

Your language or framework generally has a style guide. Depending on the language or framework being used that may be sufficient to normalize the code style. You could integrate automated style checking into the CI process depending on what tooling is available in your language, although getting the current codebase to a state that is acceptable to the tool may be a significant amount of work..

As for the knowledge silos, you could try expanding your review process. Everyone should review all of the code. This would also help unify the style being used since everyone would be exposed to the style of everyone else.

For sharing the current architecture get some pictures describing it and make the time to go over them and field any questions. Hopefully you can generate these from the codebase itself.

Answer 2

Shared understanding mostly comes from shared conversation about what you are going to build, the why and how. Even when distributed it would help greatly if you could have a meeting together where you discuss work. Especially when estimating work together 'prior work' you could lean on tends to come out.

Otherwise you would expect a team lead to keep somewhat of an overview and being able to get you started on something while pointing out existing code you could reuse or adopt if any.

The reviewer you mentioned could also consider how a new piece of code will blend with the existing code base, if there is duplication the review could point that out..

If the system is too large for one person to keep overview then you could consider assigning a 'backup' person for each component/area which would otherwise be a silo. If not actively coding on it the backup person could at least have understanding of what the component does, what changes have been applied, for what reason, and do any code reviews to gain some deeper understanding of how it's all put together.