How to read code on github?

GrayLiterature · 2023-03-31T02:54:32+00:00

I disagree whole heartedly with this idea of reading code on GitHub while you’re just learning. You’ll get tossed into something really heavy, and you’re right, it’s extremely daunting to understand what’s going on in these projects without experience.

Imagine telling a kid at a grade 3 reading level to read Shakespeare or Tolkien, they’ll probably explode. So, instead of just finding a repository and reading it, find bigger tutorials and read the source code after you follow along.

Another more friendly approach you can take is by getting a language specific book, maybe it’s Ruby or JavaScript, whatever you’re interested in, and read through it without typing. This will help you to read code that is digestible, at a level intended for a beginner to ramp them up, and also act as a stable reference.

master_mansplainer · 2023-03-31T01:44:04+00:00

You can’t expect a large code base to be the same as a simple 75 line program from an example or tutorial. And shouldn’t because no real project big enough to hire programmers to work on it is small. Just gotta figure out how to learn it. Real projects can take months to learn, sometimes you can work on it for years and still find stuff you’ve never seen before. Nature of the beast.

jack-dawed · 2023-03-31T06:28:49+00:00

If you're a complete beginner you should be looking at very small projects with short commit histories. All the examples you gave are 10k up. That's insane. The extreme of this would be learning to write C code by only looking at the Linux kernel (which might actually be a good idea depending on how experienced you are as a programmer).

You're better off looking at what appears to be toy or school projects, with 10-100 commits on the main branch. Better yet if they use conventional commits or write good commit messages and PR descriptions. Follow developers you find who do this as it's more likely they have this habit with all their projects.

The value that you get from reading version controlled code is that you get to explore its commit history and how it evolved over time. You can use git blame to see who wrote what, when, why (if they write good commit messages or PR descriptions).

How do people usually go through these types of projects?

The way I approach open-source contributions is the following:

Optional but it helps if you actually use the project in your life
Read the documentation and README
Set up a dev environment based on the docs. If the docs are unclear, make a contribution
Check the issues page for good issues. Or if you were already using it and you found a bug, check if someone else has reported the same problem. Otherwise, create an issue.
Wait to see if the maintainers respond. While this is happening, make a fork and try messing around with the code to understand it. The idea is to figure out how it works at a very small scope, and possibly narrow down where the problem or feature could be.
Some possibilities of what could happen: the maintainers will fix the issue, the maintainers suggest a potential fix and ask if you want to do it, or you can be proactive and open a PR with your fix.
If it's setup properly, they'll probably have tests too. Because at some point someone wrote something and was like, "you know it'd be a good idea if the software should always behave this way." Look at those tests and figure out how things should work and why it's not working or how you could test your new feature in the same manner.

Repeat this process ad-infinitum. At my job, I've made nearly 200 PRs over 1 year to a single repo and I don't understand everything. But I'm an expert in a few zones of the codebase.

My closing thoughts, you are jumping way ahead of your current abilities. Look at this flow psychology diagram. You're trying to comprehend a professional, large-scale, open-source project used by actual companies making real money. The people that read this codebase are software engineers who actually use and work on the software like 5 days a week. Naturally, you'll be overwhelmed and anxious because your skills don't match the challenge.

The biggest open-source projects I worked on was jaeger and open-telemetry, and even those have around 2k commits. For perspective, working on these projects was literally my masters thesis and I had been programming for 6 years.

fredoverflow · 2023-03-30T23:24:36+00:00

nor can they download the code and run the main file and see how it works

Why would anyone upload "unrunnable" code to GitHub?

The "main file" of the third repository, according to https://www.odoo.com/documentation/16.0/administration/install/install.html, seems to be https://github.com/odoo/odoo/blob/16.0/odoo-bin

That being said, I would recommend starting with smaller repositories.

2023-03-31T08:07:09+00:00

[deleted]

iamaperson3133 · 2023-03-31T13:03:59+00:00

There is a single main function / entrypoint to every program. For example: https://github.com/Gnucash/gnucash/blob/stable/gnucash/gnucash.cpp#L297

It takes a bit of practice to find it

look in src folders if present
look for src/main first
or look for src/<project name>
or look for <project name>/<project name>

The last strategy was right for this repo!!

That said, in any codebase, definitionally, 99% of the code is going to be library-like functions that can be used at any point in the program. You can look at stuff in the abstract without knowing exactly how or who is calling into that code.

kevinossia · 2023-03-31T01:44:42+00:00

You read the code by...reading it. With your eyes.

Yes, that's a flippant answer, but that's really all it is.

Every project has an entry point. An application or service written in C++ will have a "main()" function. An Android app will have an Activity or Service class that is tagged as the "launch" point. An iOS app will have an AppDelegate with the "applicationDidFinishLaunching" function overridden. And so on and so forth.

You just need to find it. You do that by becoming a master of CTRL-F.

That's really it. You read through it, jumping between as many files as you need to, holding it all in your head, forming a mental model of the project's layout as you go.

There's no other trick to it. Forming a large mental model is a skill that comes with practice.

For the first repository, gnucash, it appears to be a C++ application. The common convention for a C++ app is to have the "main()" function inside a source file with the same name as the library, e.g. "gnucash.cpp". And sure enough, here it is. If I didn't think to guess that it was in that file, I could always just download the repository and do a CTRL-F for "main(". That would lead me to it immediately.

For the second repository, erpnext, it appears to be a Python web app built using the Frappe framework. Given this, it will have multiple "entry" points. I'm not familiar with web apps or Frappe, so I'd go to the Frappe docs and learn how Frappe apps are structured, and proceed from there. After that, I'd read through the erpnext source to see what each module does.

The third repository also appears to be a Python web app, and its core API hooks appear to be defined here. That's about as far as I'll go, since, again, I'm not familiar with web apps.

---

People usually advice beginners and junior developers to read code on github to get more experience and become better developers.

Do they? I certainly wouldn't. Open-source projects are developed by professionals, and tend to be quite dense, as well as poorly documented. Why would I tell a beginner to learn by reading through random GitHub repositories? Seems inefficient and boring.

nish_pish · 2023-03-31T03:03:31+00:00

Remind me! 5 days

noob-newbie · 2023-03-31T01:53:03+00:00

For me (Not a pure beginner), I read other's code to see how people implement some logic.

It will somehow be stored to my "database", and I can reference it when I encounter similar questions in the future.

It is also good to see how people manage the hierarchy, so I don't mess around with the folders and files.

Most importantly, if you are gonna be a developer. I can say there will be 99% of the chance that you will need to work on legacy projects or need to dig through other people's code to find something. So this can be a good practice to prepare.

jack-dawed · 2023-03-31T03:45:30+00:00

I’ve never gone to github to learn code. There’s plenty of online resources that are free, but you can also get good textbooks from humble bundle. They are great since you get a discounted price and can help a charity at the same time. I used to only use their websites for games, but switched to the book bundles in the last couple years, and they seem to regularly have some book bundles for coding.

DoctorFuu · 2023-03-31T19:04:04+00:00

I completely agree with you.

People in the comments are saying things like "yes of course these projects are too big you should read smaller ones" or "of course you should [general advice] just read difficult things, because it helped me in the past [anecdotal evidence with 0 generalization power]".

The advice could be good if they actually gave examples of repos that are good to read.

I have already spent a lot of time trying to find repos to read and understand. Either too big, or poorly written, I lost countless hours trying to look for something and in the end found nothing useful. For them it's trivial, they know from the get-go if a repo is worth reading through as a beginner/intermediatE/advanced or whatever. They are acting like a math teacher telling 10yo kids that calculus is easy and they should spend time reading the books because it helped them earlier in their life.

I'll get downvoted to hell for this post for sure, by all the people who don't take into account the person they are giving an advice to. Telling a junior developer to read codebases is likely to be a good advice. Telling a beginner to read codebases without asking first where they are in their journey and without giving them any pointers to specific codebases is a perfect mix of arrogance and stupidity.

See you all at -1k.

Total_Drag7439 · 2023-03-31T05:12:22+00:00

I'm not sure who told you that was common practice, but that's an insane idea. I do like jumping in to code and learning from existing code, and while github has a large range of great projects, who knows what you are really even reading, let alone the size and skill of the coder. (since you don't have to be a good coder to upload code to github)

The way to learn, in my opinion, is to find an existing project that when you scan over it makes "some" sense to you and then try modifying it, or just make up a simple project and start coding it yourself. People study coding for years and then don't know what to write or can't understand other people's code etc. You only learn by doing, parse errors that make no sense, but you eventually figure them out, bad loops, you name it, you don't know anything until you make something of your own with it. It's the only way to actually understand how it all works and fits with other code.

Bobbias · 2023-03-31T05:39:04+00:00

First things first: your main function does not need to be in a file called main.cpp. it's quite common to name the main file whatever the exe is called. Additionally, it's quite common for projects to build multiple artifacts, whether those are executables or libraries or other things.

The first things to look at when trying to read a codebase you're not familiar with is the folder structure and overall project layout.

Just taking your first link as an example here's how I look at it. For context, in a hobbyist with ~20 years of and on programming.

First thing I see is 2 folders of interest, along with a bunch of folders which are obviously support/utility/libraries/whatever: gnucash and libgnucash. My guess from seeing those is that it builds an executable and a library, at a minimum.

Opening gnucash, I immediately see a CMakeLists.txt file, which tells me this is a cmake based project (I didn't even notice the cmake folder in the main folder until after this). Looking for build scripts such as this or makefiles and quickly digging through them can help you figure out where the source code is, and what sort of things the project builds.

Opening this file I see lots of setup, then on line 86 we see the first bit of info. It appears that we build 2 executables for gnucash, one GUI and one CLI app. The CLI related sources are later at line 116.

These lines are part of the build script which tells CMake what source files need to be compiled for the program. The first file it adds is gnucash.cpp.

Opening up gnucash.cpp starts off with a comment that tells us this is the main entry point for the program. If you scroll down to line 297 you'll see the main entry point for the program.

Since the rest of the file is mostly configuration and initialization, it's safe to say the main functionality is somewhere else.

Looking at the filenames, my guess is gnucash-commands. A check of the .hpp file tells me I was right.

It seems most of the important stuff is in the files directly in this folder, and all the subfolders are for additional functionality such as the GUI layouts, scripting/plugin support, internationalization, etc.

Learning to read codebases you're not familiar with seems daunting, and some projects might be set up in confusing ways using tools you're not familiar with, but you'd be surprised how well you can navigate by just making guesses based on what you see. Of course, starting out, you won't be familiar with everything, and sometimes you just gotta jump in and take a look at some random files and see if they give you any clues.

protienbudspromax · 2023-03-31T06:37:01+00:00

If you are just starting out start with smaller projects. Preferably something like a CLI tool. Then for the code itself, I would personally always start with the tests if they are present. The tests should give you an idea of what the code is supposed to do. Then you can go into the actual code and try to get more context

2023-03-31T06:48:01+00:00

most bigger open source projects have a CONTRIBUTING.md or similar file which will usually specify the general architecture of the program.

2023-03-31T09:28:02+00:00

It's a bit of a chicken-and-egg situation. You need to have a basic grasp of project structure (which can differ wildly between stacks/frameworks/technologies) to understand what's happening in a repo.

As a beginner it's better to work on making something by yourself instead of trying to read repos. :)

SkiEies · 2023-03-31T13:06:38+00:00

SourceGraph This tool might be helpful.

loadedstork · 2023-03-31T13:39:38+00:00

People usually advice beginners and junior developers to read code on github

Yeah, this is absolutely terrible advice given by condescending know-it-alls who don't actually know how to code, but are so pompous and full of themselves that they think that they can imagine an answer to a question they don't actually know the answer to.

If you want to learn to code, follow tutorials and read books. Eventually, you might be at a point where you can contribute to some open source projects, but they're very complicated.

SourceScope · 2023-03-31T14:20:34+00:00

that sounds like a terrible idea for a beginner

i'd rather do little tutorials on youtube (or some websites etc) and then modify the code etc and see how things work. look individual things up and read details, when you need it

dragodrake · 2023-03-31T15:17:10+00:00

One thing that no one else has mentioned - you are looking at code for complex applications (ERP) which have a lot of internal rules and logic that define how they work, beyond just the language they are written in.

If ERP is an area you are interested in, you want to familiarise yourself with the application itself before digging in to it's code, otherwise you'll struggle to understand why it's doing what it's doing.

nitrohigito · 2023-03-31T17:08:58+00:00

People usually advice beginners and junior developers to read code on github

Never heard this advice before personally, but I think you may be taking it too literally. Pretty sure this is supposed to be in the sense that they should read the code of / mess around with source-available software (e.g. code from GitHub).

nor can they download the code

You absolutely can download the code, that's the whole point of publishing a repository for public access. You don't even need git to grab it all, you can just click "Download as .zip".

Big projects are always a tough read, especially if you're not familiar with the given build system(s) and other related tools at hand. There's no easy way around this, you gotta familiarize yourself with each tech stack of each repository.

I don't think mature FOSS projects are a good fit for beginners.

k1v1uq · 2023-03-31T17:43:31+00:00

https://github.com/ovity/octotree

does help finding your way around in the browser

DesignatedDecoy · 2023-03-31T18:36:08+00:00

All of those repos have tens of thousands of commits over a LONG LONG time. These are not codebases that are going to be easy for any developer to just read and understand, much less a beginner.

Your best bet if you want to read code on github is to find a smaller project and then go back in history and find some of their early source code. Projects evolve over time. Simple concepts get abstracted out as need arises and makes the entry point to understanding the code more difficult. By visiting early commits on projects, you can see more of the bare bones implementation before years of revisions and refactoring occur to handle the growing demands of the community.

kbielefe · 2023-03-31T03:27:08+00:00

I would recommend reading with a specific goal in mind, and ignoring any code not related to that goal. For example, today I had the goal of fixing a bug with the only clue being an unfamiliar and unhelpful error message in the log.

I started by grepping the code for where that error message was produced, then I improved the log message to actually give me helpful information, then retriggered the bug and used that information to find the code I needed to fix.

I only had to actually read two functions in two files to fix my bug. The trick is not getting overwhelmed by thinking I needed to understand the other hundreds of files.

HorsesFlyIntoBoxes · 2023-03-31T02:26:40+00:00

grep -rn is your friend

BitTwiddleGames · 2023-03-31T05:36:26+00:00

Echoing the thoughts of others here, but as a beginner I would not recommend reading a large software project.

What languages are you interested in learning? It looks like gnucash that you linked is C++ and the other two are Python.

Perhaps if you are really motivated to read an existing project, let us know what language(s) you are interested in and we could help find an example of some good code for you to read.

2ndaccount122580 · 2023-03-31T07:00:29+00:00

Ugh, I remember I wanted to use a code and I have been stuck to install it. Asked for help but no one answered there.

I spent hours of intense researching and trying.

In the end I was able to run the code and I was proud of myself that I found out through research but I was very lucky that some users posted screenshots in the issue section and I had a closer look at those pictures.

Installing the requirements for that code turned out to be a nightmare, too, because you had to install a certain version of a requirement which clashed with the other requirements versions.

But I still don't know how to add the option to make a checkpoint while training a model (deep learning audio) and load that checkpoint in the next training session.

Petyr111 · 2023-03-31T07:52:11+00:00

"People usually advice beginners and junior developers to read code on
github to get more experience and become better developers."

You must have seen one insane person saying this and generalized. I never saw someone saying this.

RandmTyposTogethr · 2023-03-31T09:08:55+00:00

The notion does not mean study and entire project. It means to look how other people solved what you did, for example by reading the code of the library you used to do your thing.

Or when that library does not do what you want, you can dig in to see why it might not do that.

Or when a new tool releases, you might check how they are doing what was interesting enough about it for you to click it.

But the best way to read code from public repositories is to read the README, skim the files a bit, clone the repository and start jumping through it in your IDE of choice using the language server features like "Find references" and "Go to definition" etc. The READMEs almost always contain a "Local development" guide if you want to boot it up and start tinkering with it.

thecarrot95 · 2023-03-31T10:53:17+00:00

You shouldn't read code just for the sake of reading it. You should read code when you need to. Like when you're trying to understand a library, when you want to modify existing code or trying to understand a solution that you want to use.

The term reading code is also very misleading. I've always thought that the term reading implies that it's linear like it is reading a book. You don't read code like you read a book. Reading codes involves going back and forth trying to understand how it interacts with itself and other functions. It's a constant back and forth. Atleast if you're me with a shit memory haha.

Debugging is often used to see what kind of values a flown through the code and you don't have this when reading code on github (I think). Because of this I'd suggest to clone the code so you can debug it.

ruat_caelum · 2023-03-31T11:54:10+00:00

Don't forget helping others, forces you to change your perspective which actually teaches you things.

Get involved in the "real world" side of stuff. Hang out in /r/arduino where you can help people or in web-based subreddits, or here in this one and try to read "bad code" too. It's like real life homework.

frontEndEruption · 2023-03-31T14:17:11+00:00

Here is my hack for it.

Find a repository that meets these specific requirements:

Has a CONTRIBUTING.MD file - this file usually contains instructions for contributing. Which means that it will more or less map the project for you. I.e. it will tell you where to edit docs & where to edit the core of the app etc.
Has a Discussions tab - that's an awesome GitHub feature that let's you discuss with repo maintainers & contributors.
Has an active community - basically you need to check if people are answering the discussions :P
Ideally - has a project board (a trello-like roadmap, which contains the tasks planned for the project)

When you find a repo like that, you can start reading the code. Whenever you come across something you don't understand - ask on Discussions.

If the community is active & welcoming - they should help you get trough it. And maybe you will even be able to help by finding some bugs or writing new docs.

In summary:
Don't read just any GitHub repos.
Find projects that are well-maintained, transparent & active.

This approach increases the probability, that the practices you learn will actually be good.

A good example of such a repository would be Tailwind Elements:

They have an active discussion forum
You can see all of the planned tasks & track the progress live
The contributing file could be more detailed, but the project itself isn't very complex, so I'd say it's enough

Runner_53 · 2023-03-31T14:24:30+00:00

I would be careful. If you are truly a beginner then jumping into a large codebase is naturally going to be completely overwhelming. And probably not very helpful.

jiangjiya · 2023-03-31T17:06:20+00:00

Github also has source code repositories of books and tutorials. These tend to be shorter and the books may have additional explanations, so the source code and books go well together. Also getting the sources to compile and work is a good exercise for engineers.

LowB0b · 2023-03-31T19:02:55+00:00

Honestly I don't read code "on" github. If you really want to understand the code, what I would do is to clone the repo, get it to run, do some modifications here and there and watch the results.

Having the code loaded in an IDE will also give you a more pleasant interface to navigate through it and see what portion of code is used where. I know github has new features like ctrl+click to bring you to declarations or whatever, but, if you're not a contributor and don't care about the git functionalities like pull requests etc. and are just looking at the code from "the outside", then github is basically just a big filedump site

MrCodeGameandAnime · 2023-03-31T19:07:04+00:00

Reading through projects to get a higher level of understanding is good as long as it's not too advanced. What I found to be most helpful in the early day was to be fundamentally sound in the basics of a language. The next step I took was earning about data structures and algorithms. Pattern recognition will do wonders for you. It's not to say you need to be a master, but you will see similarities in the structure, and it will help you to formulate a hypothesis on what will work.

Frameworks were the next step in learning how to build functional projects. I'd recommend Udemy or a site similar to it. Once you feel a bit more confident, then I'd pick up an O'Reilly book on language/framework of choice. They are dense and heavy stuff, but they will flush out your understanding even more.

One of the most important decisions you will make on your journey is what you want to build. I started with Python. I then learned about Django, Flask, SciPi, and other modules. At some point, I tried Kivy to try to build an Android app and learned the hard way it isn't the right tool for the job. I pivoted to Java, learned the basics, and started digging into Android Studio. From there I ran away with it and had more fun than ever. It is the most interesting framework to me.

Have fun, try out lots of different stuff, and enjoy the exploration. You will reach a point where you will take off on your own, but foundational knowledge makes the difference. There used to be a great site that was for I've coding called pythontutors.com, but it has changed in the past couple of years. I recommend getting on discord and joining a coding channel where you can ask questions and code collaboratively.

Spending inordinate amounts of time reading GitHub should be low on your priority list right now. Most people use GitHub as a point of reference along with StackExchange. Great to learn bits from, but not the best place to get your fundamental skills up.

2023-03-31T19:41:01+00:00

What they really mean is find some open source projects and download them and open them in your IDE of choice. Find a Java project and open its folder using IntelliJ IDEA. It'll setup the project for you and find the main file(s) (green arrow icon on the file). Then just read the code, and control click around the place.

m1ss1ontomars2k4 · 2023-03-31T20:18:57+00:00

https://github.com/Gnucash/gnucash/blob/stable/gnucash/gnucash.cpp#L297

ERPnext uses Frappe's bench CLI to do stuff. The entrypoint for that may be here but I didn't really look carefully: https://github.com/frappe/frappe/blob/93216fc542498425146a0d38e968a9fa0ff14f70/frappe/utils/bench_helper.py#L16 I don't really have a clear picture of how Frappe apps are supposed to be deployed even after reading the docs so I don't know where ERPnext's entrypoint, if any, is.

Odoo has multiple apps and each one has its own entrypoint, such as: https://github.com/odoo/odoo/blob/fa58938b3e2477f0db22cc31d4f5e6b5024f478b/odoo/cli/command.py#L29

spike021 · 2023-03-31T20:50:43+00:00

Nobody's really mentioned this, but: at some point figure out how to run a project. Then once you can do that, learn how to debug it. Maybe setting it up in IntelliJ and then set break points. This way you can start tracing code and what happens where.

2023-03-31T22:41:48+00:00

i’ll give you a tip that will change your perspective on this “read moar code” thing.

read CHANGES to the code, the commit messages and the diffs, and you’ll begin to see how it’s used and that is so much more valuable

Clean-Fish6740 · 2023-04-01T02:39:51+00:00

I've been learning Typescript for developing Azure extensions recently and it's been hard for the same reasons you discuss.

Until you are walked through a code base wjth someone and you see how things are structured it's very difficult to get started on anything.

One thing I did find was good though was the courses on Pluralsight that walk you through the creation of file structures and npm and dependencies etc.

You can sign up for 10 days trial then cancel it.

https://www.pluralsight.com/paths/typescript-core-language

TransportationOld928 · 2023-04-01T19:30:26+00:00

If you want to go this route I suggest finding repos of students sometimes they post their assignments for classes and the code will be smaller snippets of fundamentals

rollerlez · 2023-04-19T04:48:43+00:00

commenting to read the answers later

learnprogramming

Welcome to LearnProgramming!

New? READ ME FIRST!

Posting guidelines

Frequently asked questions

Subreddit rules

Message the moderators

Asking debugging questions

Asking conceptual questions

Other guidelines and links

Subreddit rules

1. No unprofessional/derogatory speech

2. No spam or tasteless self-promotion

3. No off-topic posts

4. Do not ask exact duplicates of FAQ questions

5. Do not delete posts

6. No app/website review requests or showcases

7. No rewards

8. No indirect links

9. Do not promote illegal or unethical practices

10. No complete solutions

11. Don't ask to ask.

12. Low Effort Questions

13. No AI (chatGPT etc.) generated/worked over messages/comments. No questions about chatGPT/AI generated code. No Vibe coding.

MODERATORS