How to read a software source code?

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 site and follow their tutorial which will eventually cover multi file projects.

1 Like

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.

1 Like

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.

Emacs and etags :slight_smile:


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.

Many thanks for the inputs.

I can see now how IDE being so helpful at finding out where certain function being defined and its references.

Found some readings on modular programming and software blueprints.

1 Like

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.