How to get start understanding source code of open source projects?

Hello,

Open source software is awesome and important for the industry. However, whenever I try to read some code for an open source project with the intent to contribute, I get scared. I get this weird anxiety and for some reason my brain freezes. I can't understand anything what the code is doing and how it's working, it looks too complicated even if I kinda understand what things are supposed to do.

I can't describe the feeling. Even if I know the language and I've learned a lot.

How do I start?

Comments

[Melvyn Sopacua]

The first thing to do is to diagnose your root issue:

• Are you used to a certain code style / formatter -or-
• Do you have problems understanding the architecture from the details

If you are used to a certain formatting style, then ironically, looking at other people's code - like open source projects - is going to help you. You just have to read lots of code and over time different formatting is not going to bother you anymore.

To diagnose: take a project that you don't understand in a programming language you are fluent in and for which you already have a preferred formatter with configuration. Then reformat the project according to your own formatting rules. If it's now much easier to understand - you have diagnosed what I call "dialect blindness".

Now, understanding the big picture from the details is a common issue in coding. The code, are the details and when you don't know the architecture behind it, the parts may not make sense. It's like being in a room without windows: you won't know if you're in a house, skyscraper or basement, on which floor, where the kitchen is or even if there is any. All you can do is look for a door and connections to other parts or a ask for a map.

And that is exactly what you can do with code as well. First, look for/at the documentation. See if it explains core concepts. Try to use the code first, to see how it works, so you can see the moving parts that are user facing.
Then open a file, see the connections between objects. Use your IDE to click from one method to methods it's invoking and paint a mental picture, or even draw one phyisically or virtually.

However - you're not expected to have a perfect understanding of the inner workings of an open source project to be able to contribute. Most projects, especially the bigger ones, will have a contribution guide and will use tags like "Easy" or "Good first issue", to mark bugs/issues/feature requests that they think can be done by someone new to the project. These are issues that aid your understanding and are usually scoped on a very small part of the project.

Last but not least - Don't be afraid to ask. If the project isn't willing to answer you and help you to become a contributor, they either don't need the help or are not equipped to help newcomers. That has nothing to do with your capabilities, so don't let it affect your spirit! Just find something else.

Hope this helps you find your way :)

[Linh Truong Cong Hong]

Thank you so much! Lots of useful information in your comment!
Indeed, it is complicated to understand the architect that structuring the projects from details (by moving between pages of code). Probably, a good project should have some kind of documents that introduce about the general architect of the project, then it would be easier for new members to catch up with!

[Patricia Ranakoski]

Hi Linh,
Sorry I haven’t contributed yet so can’t be of much help, actually I’m going to ask you how do you find open source projects to contribute? I would love start contributing as well.

All the best and hope you get good help here.

Take care

[mainrs]

Find a project you use, take a look at the issues and start working on them. Most of the people will help or guide you if you ask nicely. The good first issue label is often used for issues that are easy to solve.

The following GitHub page lists these issues and presents them nicely: github.com/topics/good-first-issue

[Patricia Ranakoski]

Thanks for answering, I’ll have a look at it

[Linh Truong Cong Hong]

Hello Patricia,

There are many open source projects available on Github. Maybe you can get started with projects related to your everyday works.

I have just figured out a very nice video on YouTube, made by a Facebook engineer, showing basic steps for contributing to an open source project:

youtube.com/watch?v=c6b6B9oN4Vg

[Patricia Ranakoski]

Thanks for sharing I’ll have a look at it , and hopefully start to contribute soon.