Live data from Hacker News

Ask HN: How do you familiarize yourself with a new codebase?

news.ycombinator.com

31–40 of 246 posts

Re: Ask HN: How do you familiarize yourself with a new codebase?

#31

Well, I'm not very good at this either but here's what I do. I usually work on modular projects where there are hundreds of files in the project. I usually skip directly to locating the file where I've to make amends (using a lot of grep. grep for function and object definitions, grep for usage patterns, grep for checking how to implement something). Thus, I learn about the codebase as I go along. Sure, this is not t…

If this is your modus operandi your life will be much improved with Ack. It's specifically designed for searching codebases.

Re: Ask HN: How do you familiarize yourself with a new codebase?

#32
I wrote some simple bash scripts around git which allow me to very quickly identify the most frequently-edited files, the most recently-edited files, the largest files, etc.

https://github.com/gilesbowkett/rewind

it's for assessing a project on day one, when you join, especially for "rescue mission" consulting. it's most useful for large projects.

the idea is, you need to know as much as possible right away. so you run these scripts and you get a map which immediately identifies which files are most significant. if it's edited frequently, it was edited yesterday, it was edited on the day the project began, and it's a much bigger file than any other, that's obviously the file to look at first.

we tend to view files in a list, but in reality, some files are very central, some files are out on the periphery and only interact with a few other files. you could actually draw that map, by analyzing "require" and "import" statements, but I didn't go that far with this. those vary tremendously on a language-by-language basis and would require much cleverer code. this is just a good way to hit the ground running with a basic understanding which you will very probably revise, re-evaluate, or throw away completely once you have more context.

but to answer your actual question, you do some analysis like this every time you go into an unfamiliar code base. you also need to get an idea of the basic paradigms involved, the coding style, etc. -- stuff which would be much harder to capture in a format as simple as bash scripts.

one of the best places to start is of course writing tests. Michael Feather wrote a great book about this called "Working Effectively with Legacy Code." brudgers's comment on this is good too but I have some small disagreements with it.

Re: Ask HN: How do you familiarize yourself with a new codebase?

#33
I enjoyed this presentation by Allison Kaptur on how to understand CPython better:

http://pyvideo.org/video/3465/exploring-is-never-boring-unde...

While it is focused on CPython, most of the techniques are applicable elsewhere. It also mentions a great article by Peter Seibel (http://www.gigamonkeys.com/code-reading/) that discusses why we don't often read code in the same way we would literature.

Essentially, as the complexity of software has grown people have been forced to take a more experimental approach to understand software even though it was created by other people.

Re: Ask HN: How do you familiarize yourself with a new codebase?

#34

Debugger! Surprised no one has mentioned it yet. I work in js and php, both of which I use the debugger a lot . Set a breakpoint, burn through the code. Chrome has some really nice features - you can tell it to skip over files (like jQuery) you can open the console and poke around, set variables to see what happens. Stepping though the code line by line for a few hours will soon show you the basics.

I am surprised how few younger programmers use a debugger these days.

Re: Ask HN: How do you familiarize yourself with a new codebase?

#35
I do divide-and-conquer. Find some part or feature of the tool you know from an outsider perspective, and then try to find it within the code. Then work backwards from there. Maybe even try to fiddle with it to change how it works, and see what happens.

I think reading each file or reading the data structures is more difficult because you have no familiarity as to what is going on and you have no knowledge of why things are structured as they are, so it'd end up like reading a math paper straight down: memorize a ton of definitions without knowing why, until you finally get to the gist of it.

Re: Ask HN: How do you familiarize yourself with a new codebase?

#36
The first thing I try to do is to understand the directory structure, ie where should I be looking for files? Hopefully there should be a standard structure that's used. After that I'll typically try to dig in and fix a minor bug or two. This is especially helpful if you can narrow down the part of the codebase you're working on. I also recommend using an IDE like WebStorm which will give you the ability to jump to a function definition and will help you find the functions you're calling.

One thing I do NOT recommend is changing the code style, unless you're ready to take full ownership of the project. It can make it much harder for the project owner to merge in and if there are any lingering PRs those will typically need work to merge in properly.

Re: Ask HN: How do you familiarize yourself with a new codebase?

#38

Debugger! Surprised no one has mentioned it yet. I work in js and php, both of which I use the debugger a lot . Set a breakpoint, burn through the code. Chrome has some really nice features - you can tell it to skip over files (like jQuery) you can open the console and poke around, set variables to see what happens. Stepping though the code line by line for a few hours will soon show you the basics.

What debugger do you use for PHP? I've yet to find one I really like.

xdebug and Eclipse is good enough.

Configuration got a lot easier since the installation wizard has been introduced: http://xdebug.org/wizard.php

Re: Ask HN: How do you familiarize yourself with a new codebase?

#39

When you think you understand something write a test and test your belief. If the test passes then both your knowledge and the code base are better for it. If the test fails then rewrite the test to the failure and write another test. Again you will know more and the code base will be better. Good luck.

I feel your comment should be the top one. but I disagree with this bit:

> the code base will be better.

I'd change "will be" to "might get." because this is true if you're doing unit tests that the code base can use. but sometimes you do characterization tests, which are not worth keeping around. or you might build a couple variations on "hello world" with the unfamiliar code base, just to be sure that it works the way you think it does.

Re: Ask HN: How do you familiarize yourself with a new codebase?

#40
post #34

Debugger! Surprised no one has mentioned it yet. I work in js and php, both of which I use the debugger a lot . Set a breakpoint, burn through the code. Chrome has some really nice features - you can tell it to skip over files (like jQuery) you can open the console and poke around, set variables to see what happens. Stepping though the code line by line for a few hours will soon show you the basics.

I am surprised how few younger programmers use a debugger these days.

I'm not a younger programmer and I don't use a debugger. Tried it several times and found it counterproductive.
Post reply on HN