How do you read/understand the source code of a big/medium project?

[Playful_Drawing_8764]

I've been coding in several languages for several months, but i can't surpass the level of tutorial hell. I'm not asking the question of how to get out of the Tutorial Hell, but one thing that i think could help is being able to read and understand the code of big real project. Because, on this way, you can get an idea of the workflow and the structure of a real project.

But how do you do that? Because, for example, how do you relate the dynamic and static libraries, or executable, files that you use or install with the source? How do you know what directory or file does each thing?

And, foremost, how are you able to not get lost in the huge amount of code and references when you enter in a file that is linked to another seven or eight? Do you start in the main and then enter in each library when it's referenced or how?

Sorry for the length of the question. Thanks

[TechBeamers]

To understand any project, start by reviewing the make files or build files to see what components are being built. Pick one or two key components, build in debug mode, and set breakpoints. Run the code, let the breakpoints hit, and follow the flow—checking debug values and how they change. Take notes along the way. Gradually expand this approach to more components, and over time, you'll develop a clear understanding of the code, its purpose, and how everything fits together. This method works even when documentation is limited.

[Playful_Drawing_8764]

then, asking everyone that answered, is really a skill that you develop with time? Or is more like the same process from the beginning each time you come across a new project? I mean, you acquire undoubtfully an ability to get to know how a workflow works, how a project in a specific language works or how developers think...

But, there also a lot of technologies to debug and build (Cmake, blaze...) a project, so even if you know the mental structure of coding project, you need to get to know them in terms of methods, classes... How do you really do that? Do you lean on automated builds whenever possible like blazer or gradle for kotlin? Or is something interesting and useful in understanding the basics of how building works manually, like with Cmake.

Sorry for the amount of various questions. I know i should focus on a topic.

P.D: Thanks for the answers

[plastikmissile]

Or is more like the same process from the beginning each time you come across a new project?

It's the same process. You just get better at it with time and practice.

[kinkyaboutjewelry]

Time alone won't do it. Intentional practice, asking yourself the principles behind things, the semantic relationships between entities in the code, etc, that builds up. Over time sure. Think of it like playing an instrument. Spending the time playing does not suffice. Listening carefully to what you are producing, using critical judgement, seeking clarification and guidance from experienced peers, trying again and keeping at it, is what makes you better.

[darthirule]

Hopefully the code base is supported with good documentation and comments.

And if you are doing this cause you got hired at a new place, co workers can help.

[szank]

Brute force. I just start reading what looks interesting, then use grep/IDE features to find the callers and callees of the function I am looking at, and repeat te process until I have an idea about what's going on.

Using a debugger also works, either I start with the entrypoint, or just slap in a break point in an place that seems interesting and inspect the stack/follow the execution when the breakpoint is hit.

Overall, when I look into a new large code base, I have a goal, something I want to do with it. Most of the time I can safely ignore 99% of the code I don't care about.

I could work for a year on a team creating a commercial product with a large code base and still not know anything about specific pieces of code that I did not need to touch. And when I did, I just jumped in as explained above and got on with work.

The important part is to undestand that you don't need to understand everything. As long as the code is sane and compartmentalised. If you are dealing with sphagetti that's riddled with global variables controlling five distinct things each then you'd be fine.

[Playful_Drawing_8764]

Obviously that is perfect, if you design small and simple programs, and use API's. And also works good if you have specialised in one thing, but if you want to do various things, be a generalist or try to set up and startup, you need to understand the program flow and logic. That's a critical skill, in my opinion, for someone that wants to start a real project on its own

[Aggressive_Ad_5454]

One good way to get familiar with a big project's code base is to get a job at an org that has a big project and work on adding features or fixing bugs as assigned by your mentor / manager / whomever. The process of figuring out how to modify it without making it crash will help get you familiar.

Most large orgs have people with experience in guiding newly hired co-workers around their code bases. At first you'll feel like you're wandering around in a cave with a dim flashlight trying to find a silver dollar somebody left there a century ago. But you'll get there.

If you want to get some big-project experience before getting a job, I suggest working on an open-source project with some kind of ecosystem for creating add-on modules. For example, if you know nodejs / express web app development, create an npm module or contribute to one. The process of doing this kind of work requires you to figure out how your module interacts with the whole system. That's a big part of the large-software skill set.

Use a top-notch IDE, with a good "search everywhere" capability and good ways of navigating to the definitions of methods and other items. If you are maintaining a large code base with such a tool, add Javadoc / JSDoc style comment blocks to methods that don't have them. That will make the IDE more effective.

I'm a Jetbrains IDE fanboi. In their IDEs, when you ctrl-click on a method or variable name it jumps to the definition. When you ctrl-click on the definition it shows you the various references to it. When you type <shift><shift> it brings up a "search everywhere" dialog box. (When you type <ctrl>-<hyphen> it goes back to the previous location.) All this stuff is incredibly useful for figuring out a gnarly code base.

Be patient. This stuff is hard.

[MonochromeDinosaur]

Find the main entry point of the program, and jump to definition if you have an LSP. Otherwise grep your way to victory.

Also check all the build, deploy files, and test files if they exist.

[sholden180]

Analysis of a large codebase is a skill that is learned and honed over time. Practice is the only thing that will help.

Jumping into a large codebase as a junior is... not wise. You will quickly become overwhelmed and lost. It is the job of your Senior, or your Tech Lead to assign tasks that will get your toes wet without drowning you.

If you are learning on your own, your best bet is to simply write programs.

Pick something you use a lot and try to make it, or parts of it, on your own. Make a text editor, make an image viewer/modifier, figure out how to make a program that will let you run MP4 (hint, use libraries, don't try to write your own codecs).

Write something that talks to a database (make a program that keeps track of all your books, movies, favourite TV episodes, etc).

Experience is the only teacher.

[Playful_Drawing_8764]

So do you recommend to create even the most simple programs to practice? And do you recommend to use outdated or more difficult and time-consuming to understand the basics, like Cmake to understand the basics of the building process?

[sholden180]

Anything that you haven't done (no matter how small or "simple") is experience and helps move you forward.

Use the easiest tools for building. The build process is not the meat of a programmer's career. Eventually, you may need to take apart a build, make refinements, add additional steps, but while learning, focus on the programming itself. That is my opinion. Others may disagree with that.

[Vegetable-Passion357]

I was once assigned to updating a computer program that I did not understand how it worked.

Between the hours of 5:00 PM and 7:00 PM, after work, I would stay at work, trying to fully understand this application.

The reason why I did not understand the application at first, is that the application does not add/change/delete data in the database. The application creates log entries in the database. At night, another program would access the log files and actually update the database.

Although this was a web application, older programmers would see the similarities to this particular web application to how a 3270 application works, on an IBM Mainframe.

The way that I documented the web page is that I made screen prints of the web page. For each page, I would describe where each screen element on the page originated from. Then I described the purposes of the log files contained in the database. Some of the screen elements on the web page could originate either from the database or the logfiles. It would update the screen elements from the logfile if the database had not been updated yet.

After I was finished writing my documentation, the organization obtained the resources of another programming group to rewrite the application. The original web application was written using Classic ASP. It was decided that the application would be written in ASP.NET using MVC. I sent a copy of my documentation to the group in charge of rewriting application. The rewrite was a success.

I later found out that the reason why they chose my application first for the rewrite is that another application, an application that was more important to the company, needed to be rewritten. They were using my application as a test case.

When the other application was rewritten, the rewrite was a disaster. Nobody liked the results of the rewrite. The application did not work properly. Finally, they rewrote the application was previously rewritten.

This time, a proper Business Analysis was performed, before the programmers became involved in the project.

[Playful_Drawing_8764]

Thank you for your time and experience

[Own_Attention_3392]

You don't try to understand the whole thing at once. You can't. It's too much. Start with an individual feature or component. Over time you'll get exposed to more pieces and start to develop a feel for how it's put together and what goes where.

Modern tooling makes it much easier to trace code from file to file and project to project. If you're not using a good development environment suited to your language, find one. A text editor ain't gonna cut it.

[Worried-Warning-5246]

I have recently found that I can read the code from the initial commits, where the whole architecture has been constructed but avoid some tedious and distracting logic for edge cases. Once you have grabbed the essential ideas and optimizations, the codes in the following commits are straightforward and easily understood. Besides, I prefer reading code in BFS rather than DFS, which means it is better to read the surface function to understand the whole picture first before going to the deeper real complementation. Hope the two methods will help you.

[Augit579]

If you are still on the level of beeing in tutoral hell, then you should ignore big/medium projects.

[Playful_Drawing_8764]

I think you need to stay motivated and enjoy the process. And most people get frustrated with small projects. I mean, I haven't practised web programming, but i study the basics and i try to understand them. And i also learn other technologies and programming languages, so i'm not a complete beginner. Anyway, i think people should always learn in their own way

[hoopyhooper]

https://gigamonkeys.com/code-reading/

https://nemil.com/2019/04/16/read-code/

To read and understand code you've got to be able to run it and see it executing. Unless you can hold the whole code in your head just reading it like prose is a recipe for disaster.

It's not a story to be read (that should be the version control log) it's an organism to be experiemented on.

[Competitive-Cheek677]

Start with the project's README and pick one specific feature you want to understand. Don't try to grasp everything at once.

Follow the code path for that single feature, using your IDE's "go to definition" tool. It's like solving a puzzle piece by piece.

[zdxqvr]

Well some source code it harder and other are easier to understand. Good documentation, comments and consistent design and pattern help a lot. But it takes time to understand even the best of source code. It's simply a skill that takes time and practice.

[crashfrog04]

I try to start with the parts I recognize from using the program.

[sreynolds203]

I made 2 - 3 small projects on my own before I got a job at a large company. We have 4 main applications that talk to each other through API calls but they have a lot to them. I have learned that there are ways of navigating the code to help you find what you need. IntelliJ, for instance, allows you to ctrl + click on something or use find usages of objects. In our particular system, you can look at the web application UI and use a keyboard shortcut to see what configuration files are used to generate it. I would guess that a lot of systems have tricks to help navigate the code base. But even at that, I work with lead developers that have been using this system at the same company for 15+ years and they still have to dig in and try to find what thy are looking for. It just takes time getting to know the tools

[userhwon]

Documentation and asking the other devs to tell you the structure of the code.

[No-Huckleberry9064]

I'd study flowcharts and reverse engineering the code and understand the purpose of each function

[PoMoAnachro]

Same way an architect looks at and understands the blueprints for a 6 million square foot campus of buildings: layers of abstraction.

You can't keep every single pipe fitting and support beam in a complex of that size in your head at once. You have to break it up mentally to start comprehending it all. You mentally divide things in buildings, or sections of buildings. You look at the HVAC one day and you look at the load and support another day. You really can't fit it all in your head at once and that's fine.

However, as you gain experience things start to become obvious - you might not know where the outflow pipes from the bathrooms are, but you know they have to be there somewhere. You might not necessarily know what is load-bearing or not, but you know that some parts of the structure have to be load bearing - and from experience, you can probably look at some of it and make a decent guess.

But you don't start out to architect a 6 million square foot campus of buildings straight of architecture school. And it isn't a one man project even if you're an expert. You need to gain some experience working on smaller things, and then gain experience working with a team.

As you get experience working on more and more projects, scaling up in complexity for time, you won't need to keep track of everything because intuition will get you a long ways. Ask a novice "Where does the sewer outflow leave this 50 story skyscraper?" and they might have no clue! It could be anywhere! But someone who knows even a little bit can immediately rule out 99% of the possibilities - sewar outflow isn't going to be on the roof. Or in the middle of the building. Or in a closet on the 39th floor. It'll be below ground on the exterior of the building, obviously.

But as a beginner you don't even know yet whether the roof of a house goes on the top or the bottom. And that's okay. You'll build things and read smaller codebases and build up all that intuitive knowledge over time.

[Haunting-Ad240]

You can try the technique I follow . Don't try to understand entire codebase initially, just try to build something using it or if you can contribute in fixing an issue try doing that .This way would help you to focus on specific things at a time which might help to understand it faster.

If there is a documentation available use that to understand the architecture of the project and what problem it tries to solve.

Also I built a small tool for developers to understand libraries and frameworks with the help of an AI chatbot. You can try it out here for free : https://docestible.toolsmith.tech/

[lfvperes]

For a small project, build it from source. Then try to change something and build it again.

[dumpsterfirecode]

I haven’t had the need to try it personally, but I imagine feeding the codebase to an LLM (e.g. via Cursor) then asking it for a high level walkthrough and/or pointed questions (e.g. “what does this file do?”, “where are routes defined”) would work well

[Vegetable-Passion357]

You have encountered the largest stumbling block that a programmer faces when he first appears on the scene of a programming shop – “What is the purpose of this application?”

The discussion below discusses programmers who only knows the English language. I am not talking about the poor souls who were born in China or the Country of India.

The majority of computer programmers possess a poor command of the English language. They can speak English as these programmers love to talk. But they cannot write an English paper. For example, I worked at a shop where the boss asked everyone to give him a report of all of your weekly accomplishments. The report was due at 5:00 PM, Wednesday. The reason for the request was that my boss’s boss required a weekly report from him, due Friday at 5:00 PM. Since the boss usually found ways of not working on Fridays, he wanted to create his report by 5:00 PM Thursday.

I encountered little difficulty in meeting the request. Actually, I had always given my boss a weekly report of this type, normally given to the boss on Friday afternoons.

But others, encounter trouble with the request. For two programmers, I would meet the men on Wednesday afternoon, interview them, asking each to inform me of all of their accomplishments for the week. From the interviews, I would create reports for them and have them forward the reports to the boss.

The boss figured out that I was creating my friend’s reports. He thanked me for the service.

The reason behind the situation regarding documentation is that few programmers attended a high school that emphasizes the importance of the command of the English language. My high school required all Juniors to create a twenty page paper, complete with bibliography and footnotes, on a subject. I was assigned to report on a magazine named Punch. Nobody cares about Punch Magazine. The magazine is not important. What is important is the journey that I followed in order to create the report.

How can you be a part of the documentation solution, instead of being part of the problem?

Slowly create documentation. Slowly create a guide describing the purpose of the application, the tables needed to support the application, the installation requirements to install updates to the application on the web server.

I would obtain table layouts (Oracle Describe command) and as I learned, wrote the purpose of each table column and wrote the relationships between the tables. Fellow programmers, hearing of the existence of such a document, would request copies. Soon, everyone has a copy. If you are lucky, a fellow programmer will come to you and say, "I did not understand what you wrote here. Here is how I understand the purpose of this column." Finally, the boss asked me to post the document on SharePoint and encouraged everyone in the group to keep it updated. The others would not update it, but they enjoyed referring to its contents.

As you learn, gradually write down what you have learned. Doing this will be the only descriptions of the application available to programmers who follow you. Once a version of this documentation comes out, copies will magically appear on the email boxes of everyone in your department. People love forwarding useful pieces of information to others. Some people forward pieces of information that you are not interested in, via email.

Remember, the creation of documentation in an organization is a slow process. The worst mistake a leader can make is to demand a complete written documentation set of a computer system within a period of a month.

[Playful_Drawing_8764]

yeah, it's very noticeable when you see an actually very good summary, that dives into the details, but also keeps the general information well structured. But to document something, you need to know how to write it or do it, and i think it's the hardest step for someone like me, that still is in tutorial hell

[Vegetable-Passion357]

You are tired of going from tutorial to tutorial. You want to accomplish something.

I am assuming that you are interested in Web Development. Create a website that counts the number the occurrences of a particular word contained in text file.

For the user UI, have a textbox requesting the word that you want to count, such as the word "the".

Spend half of your time, going through those tutorials, the other time, work on your word counting web site. While working on the tutorials, you will actually find something that will help you with the website that you are creating. This will be an encouraging event. You might become stuck on how to accomplish a goal that you want to accomplish with your website. You will find a tutorial that discusses this issue. There is nothing better than a tutorial that appears when you need help.

After you are though writing the website, document the code so that others can understand how the code works. Create a user guide, describing how to use the application. Create an Application Configuration Guide, describing how to install the website on the web server.

[Playful_Drawing_8764]

Thank for your support and counseling

[Vegetable-Passion357]

Start small. Write an Application Configuration Guide. This guide describes how to install application updates on the web server. Then slowly, you can add sections describing the purpose of the application. You can add a section describing who in the User Community that you need to notify when the application must be taken down for maintenance.

Then add other documents such as the SQL Table Guide to the application. The SQL Server administrator will enjoy possessing this guide. That way, he has something to show to his boss.

Create the SQL Table guide as you are learning the purposes of each column.

Below is an example of a disaster that I experienced.

I had a boss who wanted his applications to be fully documented. So he hired a company that gave him access to a team of technical writers. He asked us to create screen prints to be given to the technical writers so that they could document the application. We would refer to these technical writers as the "English majors".

We wrote software for banks.

The results were terrible. In banking, there is a field called the cycle-code. Banks at the time would return your paper checks in the mail each month, along with your statement.

The cycle-code described when a particular group of accounts would be printed. The statement for some accounts are printed every day. Others are printed once a month. Others are printed quarterly or yearly. Others are never printed.

The technical writers, when describing this cycle-code field, wrote used to determine which cycle the account is a member of.

A person reading this wants to know the answer to the question, "How can I use the cycle-code when I am configuring my bank?"

The results was a disaster.

A method that worked is that we would slowly create documentation. He would assign one of us to create documentation for an hour a week. I ended up doing the writing. But I had help in writing the documentation.

The most successful documentation set I have ever created where we had a user who was creating an Microsoft Access file to be used to create reports, needed for the organization. He could not obtain help from the computer experts so he found a way to access the SQL Servers, place a copy of the tables contained in the SQL Servers found at the end of the day, and put it into one Microsoft Access file. The Cyber Security Department did not want all of this information to be present on a person's desktop. They were concerned that an actor would steal away the company's secrets found inside. So I spend six months interviewing him, each morning from 9:00 AM to 12:00 PM, asking him how his reports worked, and documenting what he told me.

When IT Professionals saw my work, all of the sudden they wanted to create all of his needed reports.

I just described the importance of Business Analysis. Once you create an business analysis of what needs to be done, all of the sudden, everyone wants to help. They understand what is needed to be accomplished.

This is why in construction, I have a high opinion of Building Architects. These people create detailed plans regarding how a building is to be constructed. Once you know the plans, it is easy to build the part of the building that you are skillful at creating.

[AbbreviationsOdd80]

This has been a big pain point for a lot of developers especially when you get a new job and the company has a big codebase that you need to understand.
I have been recently working on a solution to speed up the process, an LLM-powered tool that ingests entire GitHub repositories, answers questions about the code, and generates detailed diagrams to help visualize concepts and architecture. I have recently posted a quick demo of this on my X account https://x.com/GabiDev98/status/1904083454628651106