Hey there,
I have been a hobbyist programmer for quite some years and have a few smaller projects under my belt: mostly smaller GUI applications that have a few classes at maximum, make use of one or two external libraries and are very thoroughly documented and commented.
Since I love the free software movement and philosophy, I wanted to start contributing to projects I like and help them out.
The thing is, the jump from “hobbyist” to “being able to understand super-efficient compact established repos”… seems to be very hard?
Like, looking into some of these projects, I see dozens upon dozens of classes, header files, with most of them being totally oblique to me. They use syntactic constructs I cannot decipher very well because they have been optimized to irrecognizability, sometimes I cannot even find the starting point of a program properly. The code bases are decades old, use half the obscure compiler and language features, and the maintainers seem to be intimately familiar with everything to the point where I don’t even know what’s what or where to start. My projects were usually like four source files or so, not massive repositories with hundreds of scattered files, external configurations, edge cases, factories of factories, and so on.
If I want to change a simple thing like a placement of a button or - god knows! - introduce a new feature, I would not even remotely know where to start.
Is it just an extreme difficulty spike at this point that I have to trial-and-error through, or am I doing anything wrong?
I’ve been a dev for 20+ years and yeah, learning a new repo is hard. Here’s some stuff I’ve learned:
Before digging into the code:
- get the thing running and get familiar with exercising it: test happy path, edge cases, and corner cases. We’re not even looking at code yet; we’re just getting a feel for how it behaves.
- next up, see if there’s existing documentation. That’s not an end-all solution, but it’s good to see what the people that wrote the thing say about it.
Digging into the code:
- grep is your very best friend. Pick a behavior or feature you want to try and search for it in the codebase. User-facing strings and log statements are a good place to start. If you’re very lucky, you can trace it down to a line of code and search up and down from there. If you’re unlucky, they’ll take you to a localization package and you’ll have to search based on that ID.
- git blame is also your very best friend. Once you’ve got an idea where you’re working, use the blame feature on github to tie commits to PRs. This will give you a good idea of what contributing to the PR looks like, and what changes you’ll have to make for an acceptable PR.
- unit tests are also a good method of stealth documentation. You can see what different areas of the code look like in isolation, what they require, and how they behave.
- keep your own documentation file with your findings. The act of writing things down reinforces those things in your mind. They’ll be easier to recall and work with.
- if there’s an official channel for questions / support, make use of it. Try to strike a balance here: you don’t want to blow them up every five minutes, but you also don’t want to churn on a thing for days if there’s an easy answer. This is a good skill to develop in general: knowing when to ask for help, knowing when an answer will actually be helpful, and knowing when to dig for a few minutes first.
There’s no silver bullet. Just keep acquiring information until you’re comfortable.
grep is your very best friend.
This. And also, in many cases, an ‘adjacent’ grep may help. Say you want to move the “OK” button on one screen. Searching for the string “OK” would be overwhelming as that would be all over the shop.
But you notice there’s a “Setup…” button next to it. Searching for that could potentially cut down your search results by orders of magnitude. The more obscure the text, the better.
I’m a software engineer by profession and passion and have been writing programs for well over 20 years now. I believe your experience is totally natural - at least I share the same feelings:
-
Large code bases take time getting to know and understand: most definitely true. It takes time and effort and is an investment you need to make before being able to feel confident. You don’t need to fully comprehend every aspect of the project before you can contribute but you sure need to have a decent enough idea of how to build, test, run and deploy a particular feature. See point (2).
-
Don’t let the size of the project intimidate you. Start small and expand your knowledge base as you go. Usually one good starting point is simply building the project, running tests and deploying it (if applicable.) Then try to take on simple tasks (eg from the project’s issue tracker) and deliver on those (even things like fixing the installation docs, typos, …) That’ll have the additional impact of making you feel good about the work that you’re doing and what you’re learning. I’m sure at this stage you will “know” when you’re confident enough to work on tasks which are a bit bigger.
-
During (1) and (2), please please do NOT be tempted to just blindly copy-paste stuff at the first sign of trouble. Instead invest some time and try to understand things, what is failing and why it is so. Once you do, it’s totally fine to copy-paste.
After all, there’s no clear cut formula. Each project is a living and breathing creature and “not one of them is like another.” The only general guideline is patience, curiosity and incremental work.
Im a programmer for work and honestly feel the same. Everyone says I’m doing a good job but I feel like it takes me forever to understand a new code base. I can’t just read a program and understand it. I need to copy and paste bits and try copy a feature to get my head around it. Like if there’s a button on the GUI then I follow it right the way through creating my own button. But I don’t know if there’s a better way to learn than that
There’s a lot of great advice here already; I’ve got one more piece from trying to figure out GIMP a few years ago.
Read the old commit notes and implementations. Treat them like your favorite soap opera. Get emotional about it; have your heroes and villains.
By the time you’ve gone from 1998 to 2015, you’ll have a thorough understanding of what’s going through everybody’s heads when they look at the code.
Is it just an extreme difficulty spike at this point that I have to trial-and-error through, or am I doing anything wrong?
I would say this is the biggest ‘aha’ moment for pretty much any developer - the first time you go from “I built this myself” to “A team built this and has supported it for 10+ years”. Not only can a team of three or four write a lot of code in ten years - they’ll optimize the Hell out of it. It’s ten years worth of edge case bugs, attempts to go faster, new features, etc. And it’s ‘bumpy’ because some of it was done by Dev A in their own style, some of it by Dev B, and so on. So you’ll find the most beautiful implementation for problems that you haven’t even considered before next to “Hello World” level implementation on something else.
The biggest thing you can do to help yourself out is make sure you’re clear on their branching strategy. When you’re the only one working on your code, it’s cool to push to main and occasionally break things and no harm no foul. But for a mature code base, a butterfly flapping its wings on that obscure constructor can have a blast radius of ‘okay, we have to rebase to the last stable commit’. When in doubt, ‘feature/(what you’re working on)’; but there might be more requirements than that, and it’s okay to ask. Some teams have feature requests tracked by number, on a kanban board, some put it in their username, etc.
Get the code pulled down, get it running on your machine (no small task), git checkout -b from wherever you’re pulling a branch off of (hopefully main or master, but again, it’s okay to ask) and then, figure out what the team’s requirements are for PRs. Do they have any testing environments, besides building it locally? Do they use linting or some other process to enforce style on PR reviews?
And then…don’t move a button. (Unless that button actually needs moved!) But try to mimic something that already exists. Create a second button in the new location. Steal from the codebase - implement something small in a way that has been done before. After the new button works - then remove the old button and see what happens.
The longer you deal with a codebase (and the attendant issues and feedback) the more you’ll feel yourself drawn to certain parts of the code that you’re familiar with.
Anyway, hope that advice helps! But most of all, don’t be scared. You will break things unintentionally. Your code will break things. If there’s not a process in place to catch it before it happens, that’s not your fault; that’s the senior dev/owners fault. But do try to limit the damage by using good branching strategies, only PRing after linting/testing, and otherwise following the rules.
