understand ANY programming project (from an open source maintainer)

Creating a project is challenging and fun, while maintaining the project is where you figure out what tech debt REALLY means. It can be a great way to sharpen your skills as a developer and learn from previous developer's designs and implementations. It can also be incredibly overwhelming to jump into a new codebase head first.

Bashbunni can often be found hopping between up to ten different programming projects in the span of a week. This is what she's learned along the way.

Related links:

My other corners of the Internet:

Chapters:
0:00 the struggle bus
0:38 get good with your tools
0:59 fighting with doom emacs
1:25 how I search a codebase
1:59 SOS: no documentation or tests
2:23 programmer's chicken scratch
2:33 example notes
2:50 helping future bunni
3:03 summary
3:35 byebye

#opensource #programminglife #programming

[bashbunni]

It's really candid, but let me know if you enjoy that format!

[EditsByShobhit]

dude the pen and paper thing is so underrated. every time it's got confusing for me, i'll always write it down and see the whole flow

I never thought of looking at tests first. Interesting approach. I've always just read the code I was interested in from top to bottom.

[dylanelens]

In my opinion, I usually look at older pull requests. this helps a lot for me

[pointer]

I was wondering what value you could possibly provide in 3.5 minutes, but to my surprise, these appear to be excellent points! Thank you!

[Sventimir]

Reading tests for understanding the code is good, but even better is writing new tests. A practice that let me quickly understand parts of systems I was new to was to write some tests (esp. high level integration tests). Often I didn't really know what assertions I should really put into the test, but guessing the right assertions and seeing whether they pass or not is great for understanding new codebase quickly and deeply. That way you get a fast feedback on whether you're thinking in the right direction or not. This practice works miracles in languages with strong static type systems, where types already tell you a lot about what to expect from a certain function or module. The story might have been much different in weak/dynamic type systems (which is part of why I generally avoid these as much as possible).

[slothlair]

The "confession" is just using the best tool for the job, so nice work. These are all good tips, thanks for the perspective!

[xspager]

As someone who had to go through comercial code without much tests for a long time I'm only recently enjoying the privilege of looking at tests to get familiar with code, and it really really helps.

[agurra]

I feel like pen and paper for code are about building your reasoning around a problem from scratch (or from where you're reading it :)). I have always used it to iterate and design stuff, and one efficient digital equivalent of it for me has been to simply write it down even in the computer. I have been using Obsidian as I like how it renders and also it has these Canvases in which you can visually build mind maps, and reference even existing notes you have somewhere else. It's almost like the Pepe Silva meme by the end of it.

I think graphs (as in the node/edge thing) are overall really helpful. But building the graph on your own is what actually gets it into your brain somehow.

Thanks for the tips!

[SupreetSinghsuppi]

One tip I would like to add, projects such as the Linux Kernel, have a lot of documentation and websites online that clearly define how we should do a certain things. Search the Web and Read the Manual for anyone who is trying to contribute to any project, before you reach out to a maintainer to ask questions. Take your time, and with time you will get good.

[willmedrano]

I love good 'ol pen(cil) and paper. I never reference most of the notes I write, but the act of creating it is great for my learning.

[joostlekkerkerker]

I think one of the important points with contributing to open source is staying humble. Maintainers who question why you do the things you do want to know the thought process behind this, and if that question gets asked, that means that it's not clear right now. It's always so annoying to get first time contributors talking out of their ivory towers that they know best.

As a maintainer of one of the biggest open source projects, that's a good reason to just spend less time on your PRs because I have a bad time reviewing it.

[asdfasdf]

i have used a regepx on a spreadsheet, where columns are the regexp and rows are filenames. it gives a good interactive dive in into a vast code base. nice video, thanks

[hawkandraven]

"grep -Rn" over the whole source code folder is such a huge help sometimes, even when working on a (huge) codebase I alreade worked on for years. For every comsole and GUI project, you can start with that by grepping for the closest text appearing on your screen, high chance it appears verbatim in the code somewhere, in a place where you can start to dig down right to the actual code for the feature. It's a bit similar philosophy to starting with tests, I believe.

[waltwhite]

Damn, the algorithm is doing god's work these last weeks. Great vid and channel! This is useful for both open source projects and for starting a new job (if the company has any tests written, ofc lol)

[ToyKeeper]

Good tips, especially the part about pen and paper (or a text file) to trace through things and understand how stuff works. It's hard to go wrong with _reading_ the code, tracing it in your head, and making your own documentation about how it works. As for tests though... sigh. Tests are great when they exist, but a lot of the time they don't. Especially in the early phases of a project which is doing something brand new instead of retreading established territory, when it's not even clear what a program should do or how, tests can be really impractical. Or when trying to fix abandoned old code which was written poorly but is too important to just discard. Or low-level embedded stuff where it's basically impossible to automate the testing. So I often end up doing manual tests just using the scientific method, coming up with a hypothesis, modifying a line of code to visibly indicate a test result, and then running it to see what happens.

[sthmrtn]

Setting up a debugger in whatever editor you use is super worthwhile. I can't post a link outside of youtube here but I wrote a post detailing how to setup a debugger in vscode, neovim, emacs, and the terminal on my blog. You get to it from my profile.

Main point is that your editors do not have debuggers. They use the language's debugger. So debugging in emacs or neovim or vscode or the terminal is the same thing. Just setting up the tool to use the debugger is the tricky bit.

[QWRTYUU]

Those are pretty good! I usually try to wrap my head around the structure of the code, the alt click a lot to find references and uses with the problematic variables or functions.

Also just doing this a lot is key — you will realize that code is code and reading it is very similar in all cases. Never thought of drawing it tbh!

[frustratedalien]

I write Python/C++ professionally and I use VSCode as my primary editor because it just works most of the time, especially while remote debugging (my corporate machine is a Mac but 99% of my development is done on two Debian VMs, one in the cloud and another local). I still use vim/neovim for smaller personal projects, but that's because I can spend time to set things up or learn as I go. When i am working professionally, I wanna get stuff out as fast as I possibly can regardless of the tools. Of course, it is a skill issue. If I was great at neovim, I'd probably have found a way around this lol, but you don't have to frame it as a spicy take. VSCode is awesome

[the_yugandharr]

yeah that was super helpful. i used always think i need to read the entire codebase or a large part of it to be able to contribute but yeah using tests and debuggers to really narrow down bugs is an amazing way!