Too many code projects in research are done by a single person. Keep reading on why that's bad and how to do better.
It’s been a while since my last post. Founding the Digital Research Academy, holidays and LOTS AND LOTS of workshops and events have taken all my time. But it’s time to start writing again.
One of the workshops I taught since my last post was on collaborative coding at the wonderful RSE summer school at KIT (click through the timetable to find all kinds of cool materials).
There is more to collaboration than we see. The Turing Way project illustration by Scriberia. Used under a CC-BY 4.0 licence. DOI: 10.5281/zenodo.3332807.
But why is collaboration in coding even relevant? Why teach it at a summer school? I think most code projects would benefit from at least two people involved. That includes research software projects, projects that require complex computer simulations, but also research projects with simple data analyses, because
it is so easy to make mistakes in programming and a second person taking a look just makes sense,
most of these projects require someone who is more of a coder and someone with more domain expertise, and
if one person can’t continue the project it shouldn’t die because of that (bus factor).
In other words, collaborative coding
improves code quality,
allows for knowledge diversity, and
promotes longevity.
Collaboration and with that also collaborative coding is multi-layered and complex. Let’s talk about a few of the things that I found helpful for myself when it comes to collaborative coding.
Setting up a collaborative project
Collaboration workflows
Communication and soft skills
Setting up a collaborative project
To work together effectively, we need to set up our code projects in an organized way, such that everyone in the team (and potential new people to be onboarded) can understand what belongs where and what each file contains.
The three building blocks that I find most relevant here are:
good file and folder organisation,
good naming of files, folder, functions, …, and
documentation (at least a README).
I wrote about setting up a repository in a previous post. Check that out for awesome templates.
Collaboration workflows
How do you want to collaborate on a code project? Do you want to do peer coding and sit side by side while you code together? Do you want to split up the work and one person codes the first part, one the second and so on? Do you want to work simultaneously on things?
Whatever you do, I suggest using version control - more specifically Git (with e.g. GitLab/GitHub) - when you work with code. A common collaborative workflow works as follows:
There is a main branch that is the “stable version” of the code.
Each collaborator works on a separate branch for their part of the work.
Once your part is done, you create a Merge Request (that’s what it’s called on GitLab, “Pull Request” on GitHub), which asks for your branch to be merged with the main branch.
Someone else from the team reviews the changes and gives feedback. Once everything looks good, they accept the Merge Request.
If your project is popular enought, you may sometimes get contributions from people you don’t know. In this case you probably want them to use forks instead of branches.
Branches: Branches are essentially separate versions of the codebase within the same repository. They allow developers to work on different features or fixes independently of each other and of the main code.
Forks: A fork is a copy of a repository that exists as a separate project in your GitHub or GitLab account. Forks are commonly used when you don’t have direct access to a repository (e.g., contributing to an open-source project), allowing you to make changes independently before proposing them back to the main repository.
Communication and soft skills
Communication is key when it comes to good collaboration. The way people in the project behave towards one another can make or break a project.
As such it makes sense to consider these things. Nowadays many projects have a contributing guide but also a code of conduct. Let me leave you with a list of things to consider when it comes to communication and soft skills and a few helpful links in case you want to dive deeper into it:
I am excited to share that the Digital Research Academy incorporation is almost done. We had our notary appointment last week, set up the bank account and are now waiting for the official registration of the DRA Digital Research Academy GmbH. I published my first post about the initial idea for the Digital Research Academy in May 2023. Now, just a year and a few months later, the Digital Research Academy is becoming not only an initiative but a company. Last week Joyce Kao, Melanie Imming and...
I am in the process of making my newsletter FAIR (Findable, Accessible, Interoperable, and Reusable). Here's how. I am an advocate for Open Science. The FAIR priciples are very near and dear to my heart. I was excited when the Open Science folks at Jülich archived a bunch of my posts and gave them a persistent identifier (DOI, see archived posts here). This was exactly what I was still missing to make my posts more FAIR. However, I cannot expect them to take care of archiving all my posts and...
I get asked for career advice all the time (even though I am just figuring stuff out myself). Generally I try to help by listening and asking questions, but there is one thing that I tell everyone who wants to hear it: pick work where you like the people. How do you pick the research group you want to work with? My recommendation is to pick based on two things: Do you like the topics they work on? Do you get along with the people in the group (in particular your boss/supervisor)? The first is...
