, ,

Hello today I’m going to talk about how to read, understand and successfully modify open source code.

At first I just want to say that I’m going to be talking about what I do when I try to understand open source code, and that I have written this I n respect to c++ projects (which I mostly work on) but I think this could apply to about any programming language or project you are trying to understand it’s code.

Well let’s you are feeling like looking at some code in order to improve your skills at a certain language or to understand a certain programming concept, or just to have fun (well mostly it is fun)

so you googled for an open source arcade game or whatever you are interested in and you found that innocent project that has about 20 headers and 20 source files. And you were like: ehhh now what? , well now you have to understand it and make something out of it that will help you or anybody. But that could be somewhat difficult (especially if it’s your first time), So I wrote this in order to share what I do when I’m in that situation.

for me, I mostly follow three simple yet very useful steps, here they are:

step 1: know which files you need to start looking at


look at the source files and watch out for the most included files in the source code

for example if you have like 10 header files then look at there includes and if they have a file (e.g #include <Defines.h> then this is the file you need to start playing with.

However, if the header file have no commonly included file then it’s best if you just pick any file that seems the most abstract one (the header that most sources depend on or the header that has only included STL and dependencies headers and no header from it’s own project)

step 2: play with it !


start playing with some values and defines it has then compile and run the program and see

what happens (or what you messed up!) cause this will make you develop certain feelings for that program (don’t worry you can’t marry it), And most importantly it will give you a sense of

how the program works. And if possible try to track where the value’s that you have changed are used

NOTE: don’t change all the values in that file because this will get you a headache, instead change only some values once at a time and if you want to play it easy then just play with one

value at a time

step 3: Do the same thing with step 2 but with functions


try to figure out what the most used functions are and understand what they do. then, if possible,

play with there inner working then watch what happens when you compile and run the program.

step 4: the most important step (not actually a step as you need to do it all the time)


comment then comment and once you have finished comment again!.

Once you understood something about the code then comment it instantly it doesn’t matter where you put the comment for example you could make a ” my comments” section at the end of each file or you could put the comment between the lines of your code, for me I always try to put the comment right next to the value definition if I figured out what this code is used for

or put it right under the function definition if I figured out what this particular function does.

And I do the same thing with classes, structs, enums, and just about every thing

that means once I understood everything about the functions and definitions in a particular file

then it’s going to have a hell lot of comments. And I think this is the right way to understand all the code of open source project’s or at least the bits of code that you want to understand.

if you have anything to add, That’s what comments are for.

And thanks for reading.