How to architect a codebase for short-term contributors?

Question

I recently joined a tiny nonprofit whose flagship product is based on a decades-old C codebase, and I've been brainstorming with a senior developer about things I can do to help make working with all the legacy code easier.

Here's the complication: this nonprofit has no resources to hire full-time developers (it's just me and the senior guy), and so a lot of our work is done by short-term volunteers. Unpaid interns, professional developers who give us some of their free time, people at hackathon type events, etc. Many summers there's a ratio of something like 1 full time developer to 5 interns.

Based on books and my experiences in more typical companies, so far I've come up with ideas like:

• better and more thorough testing
• IDE tooling like intellisense-type things
• moving away from more obscure frameworks and languages
• CI tooling like a continuous build
• well defined processes for things like Git workflow
• more thorough and accessible documentation, especially for the initial codebase orientation stuff

...but all of this is based on my knowledge/experience from places that have full-time, long-term developers that can actually get fully onboarded and comfortable with all the processes. My nonprofit's challenge is not so much "what tools should we give this full time developer so they can be as productive as possible?" - it's "how do we onboard a volunteer to this gnarly codebase and all the associated tooling/processes as fast as possible, so they can actually get something done in their <= 3 month tenure?"

So my question is: what unique architecture/DevOps considerations should I be thinking about when I'm dealing with so many short-term contributors? What strategies should I be using here?

Answer 1

Your challenge looks very similar to open source projects, which may have several hundreds if not thousands contributors, the majority of them contributing only for a limited time. Take opensll for example: it has around 800 contributors, but 700 made less than 10 commits and contributed for a very limited time.

The open source community practices may therefore work well for you even if your context is slightly different:

• Most important is the source code repository. Git is your friend to make sure it will keep memory of everything that happened to the code. But you'll need to provide guidance on the most suitable workflow.

• Then you need to have a shared understanding. This means to define a clear code of conduct, a well defined workflow, and a documentation strategy. Automatic documentation maintained with and generated from the code certainly helps. Some overview documents about the architecture should also be maintained to help newcomers get the big picture before digging into the details. But one thing for sure: documentation must be produced along with the code. Otherwise, you'll end-up with unmaintainable chunks: the intern postpones doc to the end, but delays make that the end is always farther than thought and then the internship is over and the knowledge about it is lost.

• Now there's nothing worse than getting some code delivered but not being able to know, if the next intern changes it, if it still works as it should. To achieve a long term sustainability you therefore need automated tests. TDD can help, but other approaches can deliver the same result. Not only will tests help to achieve sustainability, it also contributes to the understanding of the code base (test cases are "documentation by example").

• Finally, an issue tracker is also a must. It's a collective memory of things tha must be improved and corrected (and by the way, things we already know they do'nt work as they should).

Of course, a ready to use work environment, with the right tools and CI (or at least an automated build) is not to undersestimate: it will increase productivity and avoid loosing unnecessary time when starting something new.

Now for the architecture of the code itself, your case has absolutely nothing special. The usual OOP practices are meant to build systems out of encapsulated, decoupled and well maintainable components. SOLID, and the principe of least knowledge and similar guidances will help. There are books and books on this topic and it's too broad to be addressed here. Maybe you'll define a mandatory reading for your interns (e.g. Robert Martin's "Clean Code").