Maintaining code quality in open source

On August 17th, we did a Webinar called Maintaining Code Quality in Open Source. Guest speaker Niels Lohmann, founder of the JSON for Modern C++ on GitHub, joined our Codacy CEO Jaime Jorge in an engaging talk about open source. 

During the live talk, Jaime Jorge, Codacy CEO, moderated the conversation and asked interesting questions to our guest speaker. You can check the detailed answers on our video recording of the live talk — we even give you the specific time frames! But we’ve summarized the key points for you to read 🤓

What motivated you to start this open source project? (00:03:22)

Niels was working at the university, and they were building software in C++. They needed some way to send JSON back to a server, and there was no library for that. When things started to get more complicated, they felt the need to create a sound library.

It was also the time when C++ 11 became more popular. Scott Meyers was releasing a book called Effective Modern C++, and Niels got inspired to name the project JSON for Modern C++. Since 2013, the project‘s growth has been linear, but in 9 years, it got 31.4k stars on GitHub.

What’s the biggest challenge to maintaining code quality in open source? (00:08:07)

• People don’t think about code quality: When people what to contribute, they usually have some part of the code they want to fix or a new feature they want to add. They work on it, open a PR saying it works on their machine, and then leave. The code quality part is generality left to the maintainers. Plus, contributors often don’t know about the bigger picture. For example, their code doesn’t work in a specific compiler, and they didn’t realize it was necessary. So several times, the expectations are not always aligned. A possible solution is to have a CI tool reject the PR and automatically say what the problem is and provide a link to the documentation.
• Problems with C++: C++ 11 is old but still not adequately supported in all the compilers used today. The language is also evolving, so when a new version comes along, all the code can break, and you’ll need to make adjustments. It’s a lot of moving targets, and when you have a lot of variations, you spend a lot of time testing for all those different configurations.
• We don’t know our customers: We have no idea who and where is using our project. So it can be different use cases with different expectations. Sometimes a new use case appears that we never thought about or even knew possible.
• We have limited resources: Everybody that contributes to open source does it in their free time. Usually, the project doesn’t have access to many people or money. We are using the free tier of the CI, so it is slow. Plus, you can’t delegate things you don’t want to do. If someone opens an issue you don’t want to work on, the issue might be there forever.

What’s the hardest thing about maintaining a group of collaborators in your open source projects? (00:16:42)

• People can appear and disappear at any time. You can never guarantee that people will stay in the project until they finish some feature or release. They send you a patch, and they might disappear when you have a question. So we need to ensure that people have a very productive time, where they can focus on developing and ask them all the questions we might have before they disappear.
• Communication and misunderstandings. It’s primarily written communication, which can be a source of misunderstanding, mainly because there are hardly any native speakers. The Discord channel makes communicating easier without leaving this paper trail forever in an issue on GitHub. GitHub is also a problem because it’s not the best tool for organizing communities.
• People management. Sometimes some people take everything personally. For example, many people use C++ because they value performance above anything else, and if they feel something is slow, they immediately get outraged and personal. They even threaten that they’ll go to a different library. Yes, someone can threaten not to use your free projects.
• Expectation management. At some point, you’ll need to say no. For example, people might make proposals that are not fitting your mindset and ideas for the project. A PR doesn’t mean you have to merge; you can also close it and say it doesn’t fit your project.
• Documentation management. It’s hard work, but it’s an investment. Every documentation page has a URL you can send to people instead of writing the same answer repeatedly. At some point, you need to stop adding features and start investing in documentation because, in the end, it makes the difference between a project that people want to use and a project that people need to keep looking for information in the code.

Was there any difficult moment where your open source project affected enterprise production environments? (00:28:12)

Companies like Apple, Microsoft, Google, Volkswagen,  and Daimler use the library today. Usually, companies are some of the project’s best customers. They are very polite and never have very loud support requests. Plus, if you have a merge request from them, they’re very high quality. So everything is perfect, even in terms of communication. As Niels said, “It’s boring, but I think that’s a good thing.”

How do you celebrate? Have you met any of the collaborators in person? (00:30:44)

There are a lot of contributors from the USA, and there is no budget to meet these people. With the project moving the discussion to Discord, it’s easier to get in contact. However, some people are not there to socialize. They just want to code and improve things; it’s not the place for them to hang out and make friends.

But it’s fantastic that people do this in their free time. They spend their days writing software for money and then go home and write it for fun. That’s incredible!

What’s the biggest difference in culture between your open source work and your professional work? (00:33:07)

People are doing things just for fun, and that’s amazing. Of course, this can also happen in a professional environment, but it’s fantastic that in open source, people can motivate themselves for quite a long time. Niels talked about two features where people worked for one year, had a PR open for such a long time, and had to fix many things. There were a lot of edge cases. Eventually, it was ready, and then the person disappeared. They were there just to work on the feature and then went their way. So there is a lot of motivation, but there is also the risk of people disappearing more easily.

As a downside, open source can have a lot of discussions. Even in projects without big plans, there are always things that don’t fit the project. People repeatedly discuss the project scope in open source, but that doesn’t generally happen in a company. 

No discussion is ever over: when new people come, they don’t know the past discussions. So you must be patient and document why you have rejected each feature. People have different expectations about what could be the next steps, and they can be very emotional. 

And, of course, there are trolls. You’ll probably not find them in your day-to-day job, but you’ll find them on the internet. 

What’s the secret to balancing a professional career and your open source work? How do you do it?  (00:41:29)

The project is not something we’re doing all the time. We can work on it when we want to and if we have the time. So there is a luxury in deciding when we’re working, with no pressure.

Plus, we can try to balance what we do. If we had a lot of meetings at work and haven’t seen an IDE all day, you can go to the project and spend some time with the compiler. If we wrote code and went deep into the algorithms, in the project we go work on documentation.

Thank you to everyone who joined live and those who watched the recording later on! Let’s keep the conversation going in our community.