Post #2440730
2026-04-21 09:41 UTC
Replies (14)
-
@amenonsen@flipping.rocks 2026-04-21 09:49
@liw@toot.liw.fi My favourite way was to use Sourcetrail to read through the source (preferably with some specific question in mind, but not always) while seeing diagrams of the relationships between functions, objects, etc. But alas, the Sourcetrail authors weren't able to make it a commercial success, and gave up on it. Pity.
-
@talios@mastodon.nz 2026-04-21 09:54
@liw@toot.liw.fi Often reading thu commits, if I'm looking for certain areas of the code it’s kinda nice to search the repo history for keywords, and see what paths pop out, discover the churn, see what tickets are referenced that I can read for more information. Thinking thats something claude/ai could do to summarise - grep the commits, extract ticket references, look up the ticket in YouTrack / GH etc. and summarise recent issue.
-
@srtcd424@mas.to 2026-04-21 09:57
@liw@toot.liw.fi ways to document the code architecture, entry points, data flows, etc are a problem I really don't feel we've cracked, especially in open source :(
-
@apsmith@fediscience.org 2026-04-21 11:26
@liw@toot.liw.fi It is best to start with a specific question - how does the code do this one thing I care about. Then trace the inputs from the main starting code through function and subroutine calls/object methods. Skip anything unrelated to your question, you can try to understand those later.
-
@sszuecs@hachyderm.io 2026-04-21 11:48
@liw@toot.liw.fi I start at looking into the program start and scroll the main flow. After that I start to see directory structure and read interesting packages. In general I see the problem of no architecture docs and no operations docs. I try to make it better in my main project, but for example in cncf projects the normal is "helm install -f https://...." and good luck figuring out how it works and what it installs. Not even to have one picture that explains all the components working together is just bad docs.
-
@gnomon@mastodon.social 2026-04-21 12:17
@liw@toot.liw.fi it's probably not optimally efficient, but I'll sometimes start by boxing out the lifecycle of the program: that is, I'll read the diff of the most recent commit to see what's still being worked on, then I'll go back and read the full contents of the initial commit to get a feel for the first working version. Then I gradually fill in the gaps with one or more other reading strategies depending on the codebase.
-
@jdm_@mastodon.social 2026-04-21 12:37
@liw@toot.liw.fi I gave a talk about my process: https://www.joshmatthews.net/cusec16/unfamiliar.html
-
@krono@toot.berlin 2026-04-21 20:17
@liw@toot.liw.fi I start reading the tests. They tell me the api and whats toplevel and whats support. also, the expected order of things. (Then I abandon all hope cause I deep dive depth first and get lost, but thats on me)
-
@partim@social.tchncs.de 2026-04-21 20:26
@liw@toot.liw.fi Having a particular issue to solve. This shifts the goal from the overwhelming having to understand the whole thing to just having to figure out how a specific aspect works. You don’t feel lost because you know what you are looking for. And while looking, you discover how the whole thing hangs together more or less by accident.
-
@pozorvlak@mathstodon.xyz 2026-04-21 20:26
@liw@toot.liw.fi it's not answering *exactly* the same question, but I like this article by @DRMacIver@mastodon.social: https://drmaciver.com/2013/08/how-did-you-get-started-so-quickly/ Also, though I haven't tried it, this post: https://piechowski.io/post/git-commands-before-reading-code/
-
@florian@bsd.network 2026-04-21 20:30
@liw@toot.liw.fi figure out how a specific thing gets done. Bonus points if the thing annoys you and you want to improve it. E.g. in a cli, how a flag is implemented or how a summary line gets printed. In a gui what happens when a menu item gets selected. Basically go for depth. Then pick the next thing and go deep. After a few iterations you get a feel for the structure and it's time to go for breadth.
-
@lritter@mastodon.gamedev.place 2026-04-21 20:46
@liw@toot.liw.fi grep. you grep your ass off. i work from the context of trying to fix a bug or find a feature to modify... then explore the connections. i never see the whole project that way, but why should i.
-
@tumdum@icosahedron.website 2026-04-21 21:42
@liw@toot.liw.fi @fanf@mendeddrum.org adding lots of silly unique logs and/or calling panic! In interesting places and observing resulting backtraces.
-
@cjwatson@mastodon.ie 2026-04-21 23:34
@liw@toot.liw.fi Lots of good advice in this thread. Other miscellaneous things I've used successfully: * Fix something simple and debug it when it doesn't work. Repeat until things start to make sense. * Often you need to know how something is used. Don't underestimate low-tech approaches. Set a breakpoint or print something loud and run tests until you hit it, or just deliberately break it and see what else breaks as a result. * Use VCS history. `tig -Sthing` is a superpower.