Hi, newbie in programming here. Can someone guide me how to read source code?
In school i’ve only ever code in a single file source code like test.cpp. But how to read a source code that have different directories (eg. assets, cmd, lib, etc.). How the developers dictate which code belongs to which directory?
Is there anything I can read on this? I did go through a few software engineering books but i cant find any info of how the software being structured into directories. Thanks!
Source code example (Syncthing) that I want to read from github:
Essentially you are goinf to need to import the project into an IDE. This will look qt the files and references and try to link them up. You can look at the cprogramming.com site and follow their tutorial which will eventually cover multi file projects.
There’s not typically a strict structure to the directories other than the programmer(s) decide upon. Typically though there are some sort of import statements at the top of each source file which shows which other files and outside libraries are being used in that file. I’d suggest looking at much simpler multifile projects first since Syncthing appears to have a not so simple structure to it for someone that doesn’t have experience.
Often times you can figure out what is in each directory by the name:
Assets - presumably all of the icons, logos, documentation pictures, etc
cmd - probably the source code for the command line interface
etc - probably default configuration files to go in /etc
gui - source code for the web gui
lib - probably the “main” source code for syncthing itself, in some projects a directy called lib could be third party libraries
man - documentation
script - build/test/deploy scripts
test - unit tests, integration tests
As @2FA said, it is pretty much up to the developer for what they want to put where. Depending on the language and build system, there are often common trends, and if the project was created in an IDE there is a default structure, but otherwise, it is totally up to the developer.
I would also second @Mastic_Warrior’s recommendation for using an IDE, so you can click something and figure out where it comes from.
You also can use grep -r, ripgrep, or similar to find all references to something.
I still do that a lot even when working with code with which I am familiar. Sometimes I’ll remember what the code does, but not what file it’s in, and IDEs that are super aggressive with their suggestions piss me off, so a-grep-ing I will go.
github is really bad for it … it may work for you once you get more experience with the code base, …or get used to really large code bases. It also helps if you have experience with similar project, or know the particular programming language or frameworks used well.
In this case I’d clone the repo locally, I’d open it in vscode that lets me jump around the code base easily following method calls and so on.
I see there’s docker files around for building it, I’d try looking for any build instructions of development instructions. (sometimes you get lucky and tool/code ends up being well documented). Once I can build it, I’d probably sprinkle logging or printf statements around (more rarely in a general case I’d use a debugger).
Also, personally I keep a pen and an a4 notebook handy, and I make a big mug of tea and ensure in advance that I have enough time to sit down and focus without distractions, until I figure stuff out.
Browsing the git commit history and seeing what files are touched when implementing particular things can be a good primer on how the code is structured.
