Re: “I Don’t Want To Maintain Their Code”
Software architecture

Re: “I Don’t Want To Maintain Their Code”

How can we facilitate knowledge sharing? Will easily accessible documentation foster cooperation?
Bartosz Mikulski
Bartosz Mikulski – 5 min read

The Beekey Cheung’s blog post begins with a rather sad story.

Table of Contents

  1. Decisions
  2. Architecture Decision Records
  3. The wrong decisions
  4. Newcomers

(…) a team needs to hire someone (…) The reaction from one of the developers was simply: “I don’t want to maintain their code.” I understand this mentality. The worst code is always other people’s code. For most developers, this is simply fact.

In this case, the existing team does not want to maintain the code of the new person. For me, this is something new, something strange. I often saw an opposite behavior. The new person did not want to work with the existing code. Why would the team oppose maintaining the code of a newcomer?

According to the author, the problem may be related to egos of the team members. They don’t welcome a new opinion. They are afraid of being challenged. The author also says mitigating the risk may be easier if the architecture of your software is “good.”

It can’t be more ambiguous, but let’s ignore it. I don’t want to write about “best practices” and characteristics of good software architecture.

Let’s focus on something else. How do we create the architecture? Is it a random process? Is there a recipe book? Are there any rules which must always be applied? Is it created by chance or is it the outcome of our decisions?

Decisions

How can we communicate old decisions to people who join the team? In most cases, we rely on tribal knowledge. Ask your team about a decision made a year ago? What happened?

Everybody knows a part of the truth. There are gaps in the team’s knowledge. Some people fill the gaps with their own imagination and add false information. Some have problems with the timeline and talk about events which happened after you made the decision.

Sometimes you ask a few people about the same situation and hear different answers. Maybe they have already forgotten the truth. Maybe they don’t agree with the final decision and want to impose their own point of view.

What about the people who left the team? What knowledge did you lost when they quit?

Architecture Decision Records

People’s minds are the worst place to store information. How can you preserve the knowledge?

We don’t want to write long documents, make diagrams, and PowerPoint presentations. Nobody will read them anyway. Fortunately, there seems to be a simpler solution.

I like the idea of “Architecture Decision Records” described by Michael Nygard. ADRs are not long. The files should be one or two pages long. You store the files in the repository, with the code. You don’t need to look for them in Confluence or Sharepoint. The files don’t exist in someone’s mailbox or on a shared drive. You can always find them next to the code.

The format of ADRs forces you to describe not only the decision but also the situation at the time of decision making and the predicted consequences. You have to write about people and software affected by your choices, things which affect your choices, alternative approaches and the criteria you use to decide what is the best possible solution.

When a new person joins the team and starts asking questions, you can show them the files. It will probably raise even more questions. The files are not supposed to replace conversations and onboarding of new people.

So what will change? We can avoid emotions and hurt egos. You no longer try to defend your decisions and prove you were right. Now you can show them the data.

I believe it changes a lot. Only an unreasonable person would argue with the facts. Beginning a conversation with facts makes spotting such people so much easier.

What if you show them evidence and they make a preposterous suggestion? Congratulations, you just found a problem with your recruitment process.

The wrong decisions

There is one more advantage of ADRs. Writing everything down may prevent wrong decisions. Hopefully, you can spot a mistake while explaining it.

It looks like something similar to “debugging by talking to a rubber duck.” In fact, it is much better! It is like recording your conversation with the rubber duck! With multiple rubber ducks! How many people review your code? We keep ADRs in the repository, they are a part of the code. People will see them when you make a pull request. Someone may start asking questions. Someone may have a better idea.

Newcomers

Education is the only way to ensure you can maintain other people’s code. They must know what you expect. Every time someone joins your team write code with them, explain the decisions, show them your team’s style of coding, show them the infrastructure, ask them about their opinions, and learn something from them.

It is not enough to do that for a day or two. You probably need at least a month or two. Sure, it will slow down your team, but it is an investment. If your company cannot accept that, you have a much bigger problem.

You make onboarding a little bit easier if you have all required information gathered in one easily accessible place.

Do not limit your contribution to showing them some files. Documentation is not a silver bullet. It is just an additional safety net. You can’t replace knowledge transfer and cooperation with a few documents. The only reason why the documents exist is to ensure you remember everything.

Programmers don’t like to write comments. We are told to write code which is “self-documenting.” Sure, we should do that. What about the parts of our system which cannot be expressed in code?

I can read your code and see what it does. I can easily find the feature descriptions, business requirements, or UI mockups. If I am lucky, I can even find some meeting agendas. What happened to the architecture? What happened to the decisions?

The technical decisions we make are usually not documented anywhere. Our choices exist briefly on a whiteboard during the meeting. We store the decisions in our heads where they slowly deteriorate. Let’s keep them.

Older post

Discipline Equals Freedom — Jocko Willink

A review of Jocko Willink’s book: “Discipline Equals Freedom.” Should you read it even if you don’t want to run a marathon?

Newer post

Can’t learn anything? You’re doing it wrong

Have you been trying to learn something for a few months? What to do when you keep learning but still don’t understand anything?

Related Posts

Software architecture

10x software architecture: high cohesion

How to achieve high cohesion and a few common problems.
Published on: 12 Jan 2020

Are you looking for an experienced AI consultant? Do you need assistance with your RAG or Agentic Workflow?
Schedule a call, send me a message on LinkedIn. Schedule a call or send me a message on LinkedIn

>