Ask HN: How do you familiarize yourself with a new codebase?
Some background: What's motivating me to ask is that I am flirting with the idea of trying to add a couple of features to SlickGrid (https://github.com/mleibman/SlickGrid), Michael Leibman's phenomenal javascript grid widget. Unfortunately Leibman got busy and isn't actively supporting it anymore.
The codebase is something like 8k lines of javascript, so it's not ludicrously big, but I'm kind of intimidated thinking about trying to make sense of it. My first strategy is just to open up important-looking javascript files (slick.core.js, slick.grid.js) and read through for comprehension. This seems like a pretty slow way to build a mental model of the code, though. Some features I want to implement are 1. an ajax data source that doesn't require paging, and 2. frozen columns. Someone else has implemented a buggy version of frozen columns (and since abandoned the project), and I might like to use it, but I can't tell if it's buggy because it's a hard problem, or because their implementation strategy was poor (or both!). So at the moment I can't evaluate if I should implement my own, or try to fix the issues with theirs.
Picking up other people's code seems to be one of the harder tasks developers face, as evidenced by how much code gets abandoned, so I wondered if the voices of experience on here could point me in the right direction, either by talking about this problem in particular, or more generally, how you build knowledge about a new codebase.
Thanks!
245 comments
[ 7.6 ms ] story [ 177 ms ] threadFor example I would start by looking up out a basic example of that codebase and for each of the function calls go through the files and see what is happening. This gives me an idea of how the code base is written and how it works. It also gives a clear understanding of the level of separation/specificity of the different functions.
Disclaimer: not very experienced so there might be better ways to familiarising ones self with a new codebase, this is just one way of doing it and it has worked for me in the past.
http://lonnie.io/gostd/dagvis/
or this:
http://8k.lonnie.io/
Michael's code looks clean and well organized. Shouldn't be terribly difficult for someone proficient at JS.
Another thing I do is try and replicate one core feature of the thing I'm trying to understand. Like others have suggested, I like using debuggers. Recently, I wondered how debuggers work. So I built the following to find out.
https://github.com/amorphid/rails-debugger_example
As such my first steps are:
1. tidy/beautify all the code in accordance with a common standard
2. read though all of it, while making the code more clear (split up if/elsif/else christmas trees, make functions smaller, replace for loops with list processing)
While doing that i add todo comments, which usually come with questions like "what the fuck is this?" and make myself tickets with future tasks to do to clean up the codebase.
By the end of it i've looked at everything once, got a whole bunch of stuff to do, and have at least a rough understanding of what it does.
> how long have you been programming?
I was really surprised to see it, because it's exactly the way I was learning C. I switched to Linux around the same time, so I'd take some abandoned DOS program that had source code available and port it to Linux. During the process, I'd read the entire source code, make sure I understood it and reformatted everything. A few years later, the original author of one of the programs released a new version and thanks to my reformatting, it was pretty much impossible to merge. After a few similar experiences at work, I have decided to always stick with the original style of any code I touch, because any unnecessary changes are just going to make life harder for me in the future.
1. Perl is MUCH more concise than C, since we have institutionalized code sharing (see CPAN), whereas most C devs i know (and maybe i don't know too good ones) seem to at most reuse code others wrote by way of ctrl+c/ctrl+v.
2. Perl's reformatting tools are automatic. I just have a little config file that says how long my lines are supposed to be and where i'd like the spaces on my parens (inside, between the parens and arguments) and then i hit ctrl+e and boom it's done. If i need to do it to many files, find + perltidy. In your case i would've just taken his new version, automatically formatted everything in less than 5 minutes, and merged on top of that.
3. When i do this, i'm doing it with team lead consent and team concensus, in an authority position, not with random code maintained by people i never even talked to. :)
It will take months merely to tidy the code with the effect of making the rest of the team hate you for committing thousands of files for superficial changes. Its much more productive for everyone to simply adapt to the existing style guidelines.
Reading all of the code is only an option for the smallest of codebases. Reading code will only get you so far before you get lost in the complexity of how all the parts interact with each other.
A better approach would be to limit yourself to a subset of the codebase and start poking around with a debugger while the system is running. Then you can gradually work your way through the codebase starting from the core functionality.
However, don't underestimate how hard it can be to understand your own Perl code when you've been away from it for 6 months :)
For anyone who cares about their craft and has a certain amount of experience with Perl this is entirely untrue. I'd rather people not repeat this tired old meme. :(
Thank you! :)
vvvv
Neither way of learning is right or wrong and I appreciated both groups but one thing I did remember was one guy that did exactly what you did and it was highly irritating as a project lead to see relatively random files (given whatever sprint we were on) that were considered stable to show up in the source control change list with out some consideration of discussion. I would have to waste time and look what change he made to see if it was ok.
That said, it probably does scale to the OP's 8k line code base.
Also, running the code through a formatter and refactoring it all right off the bat is a sure fire way to piss off everybody else working on the project.
In any case, my 2 cents for the OP is to not bother trying to learn the whole codebase, but instead focus on just the areas you want to enhance. For example, in the case of the new data source, find out how the existing data sources are implemented, and use them as examples for adding a new one.
something usually comes up.
From my experience, there are really two ways that learning a new codebase can happen. One is that there's an existing test suite that's fairly comprehensive, and you can learn a lot by examining the tests, making changes to add features / make bug fixes, and then validate that work by rerunning the tests and adding new ones. That's really a great place to be as someone unfamiliar with a new codebase. The other is that there are no tests, and you inevitably need to rely on people familiar with the code, and make peace with the idea that you're going to write bad code that breaks things as you learn the depth of how the project works.
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.
Configuration got a lot easier since the installation wizard has been introduced: http://xdebug.org/wizard.php
But I use xdebug and phpstorm. I find it better than netbeans. Search in netbeans is good, but the whole thing has a weird GUI and is slow.
Best bet is to try a bunch.
That is incredibly powerful (PyCharm has it as well).
I remember needing to learn Ruby and Rails on an existing closed codebase and having the debugger take me right to the core of Rails several times to understand why certain things were done in a certain way in the top level code. This allowed me to get acquainted with internals of Rails and how Ruby's inheritance system much faster as well as the existing codebase that was built on top.
That's the theme I hear when prodding people who (sometimes loudly) say they don't use debuggers. They work on codebases that are either small, solo projects, or change very slowly. That way they can keep an accurate simulation of the entire program in their heads.
Meanwhile, I've always worked on codebases that were changing faster than I can keep up. The majority of my debugger time has been in code I've never seen before.
I don't find it a hindrance in any way seeing what part of the Django code called my code.
Understanding the code is often a luxury we don't have, either because we didn't write it in the first place or because there are just too many moving parts each tracking their own state and interacting with everything under the sun.
This is especially true for long-running programs that do much more than just transform inputs into outputs. For example a video game would be complete hell to develop without a solid debugger. Even if you believe you understand the complete code and all its behavior the testers will always find a way to make the game crash after 2 hours of playing leaving the game's state completely broken and without a debugger you'll be scratching your head endlessly trying to replay how that happened.
In these cases the number of different states and behaviors you can get out of the system is incredibly high, easily a few orders of magnitude more than the human brain can handle.
For me at least, that's typically my cue to start refactoring. If I can't model at least the general behavior of my program in my head, then it's probably needlessly complicated.
This isn't always possible, of course (such as in the case of long-running programs, as you mentioned; it's still possible in a lot of cases, though, and splitting off functionality into smaller, easier-to-digest pieces can make troubleshooting much easier), but it's been a useful mentality for me, and has significantly reduced the need for me to use some sort of debugger or even 'print' statements to make sense of code.
This doesn't address the original question of understanding new codebases, though.
The debugger runs in as many threads as the app itself. If you're debugging C#, and your program is in 37 threads, you can debug all of them simultaneously or debug one and ignore the others.
Understanding the code and keeping it in memory sounds like a great practice, but it also seems entirely orthogonal to using a debugger.
I have the exact opposite attitude: I live in the debugger. Most of my resistance to trying "new hot" languages is their universally terrible debuggers. (Usually they either don't exist at all, or only exist in CLI form.) IMO, if you don't have a working, stable, graphical debugger, your programming language has no business being 1.x.
If you're working on, say, a huge Java codebase, then a debugger is practically essential because you've got a lot of code to navigate, and you probably want to see what flavour of objects are being passed around and how their state is being updated.
On the other hand, if you're working on, ooh, a Nodejs codebase, you're probably looking at less code, with a debugger that's much slower, and probably more functional code that is operating on data directly. Using a debugger in that case is often slower than just using print statements.
You're saying to delete commented-out code once the new code works. Put your code in version control instead. Logging is to once-off printfs as version control is to commented-out code.
Don’t be primitive about it. :-)
The serious answer is: use a good logging framework. In particular, I’d suggest something that can log at selective levels of information for different parts of your system.
If your project’s culture is to instrument your code like this routinely, it can be a very useful asset, and it’s no more disruptive in practice than say adding comments or writing tests. In each case, with experience you get better at judging where to focus your efforts and how much detail is worth including by default, and if that turns out not to be enough you can always add more while you’re working in that area.
With modern tools for recording and analysing logs, there is relatively little useful information that you can easily find using a debugger but can’t easily find from good log output. On the other hand, logging has some big advantages: you can capture how your system changes over time, you can record and review concurrent behaviour cleanly, you can capture information from different parts of distributed systems that might be written in different programming languages or running on different devices.
Just plain "debug log statements" I have yet to hear a good use case for. Every time people have put them in, it's because some bug called for their inclusion, then the bug got fixed, then the statements got left around after the bug was fixed. Or the bug didn't get fixed and it's a matter of "why don't you fix the bug?"
There's rare cases where there's an ongoing issue with a known bug that you don't know the fix for yet, so you drop debug statements in production code hoping to catch it. But this is supposed to be a rare, rare case.
For medium/large programs I'll often prefer a debugger because I can easily and quickly try to diagnose the problem without having to wait for a new build to complete with the added traces.
You're using a primitive debugger, you just don't know it.
You can dump statements through a function and see it's progression when run without having to interact with it.
Throw in something like FirePHP (which allows dumping pretty much anything out as a viewable/collapsible trace, other languages have similiar) and the use case for a lot of using a full blown debugger is removed (it's still incredibly powerful when needed).
So I use both.
(With that said, when I have a nasty bug that requires squishing around in the guts of my program, breakpoints are invaluable. But it's a pretty huge hammer that only comes out on occasion.)
EDIT: I wonder how useful an editor that allows inline debugging code would be? Instead of setting breakpoints in your IDE and then configuring them in an individual window, you'd enter a "debugging editor" mode that would allow you to add debugger-only code for things like conditional breakpoints and printf statements right alongside your normal code. The original source files would not be edited, but while in this mode, it would appear as if they were. (Maybe the debugging code would show up in red.) That way, you could easily access all your local state and implement complicated queries without ever leaving the context of your code. In other words, it would be just like printf debugging, but once you no longer need to debug you'd just collapse those statements out by leaving the debugging editor mode and your original code would be unchanged. Perhaps this debugging code would not compile along with the rest of the code but would instead use the debugging hooks that normal breakpoints use, unless the conditions are particularly complex or something. Just a thought.
Without a debugger you're a sitting duck!
Sure, this is not the best practice, and unsuitable for many, but it's what works for me.
* Read the README.
* Install it and start using it with a couple of sample cases. That will give you an idea of what it does.
* Read the test suite. This will give you a better idea of what the library does.
* Look at the directory structure. This should tell you where things are.
* Start reading the core files.
* Start looking at open issues. Try to solve one by adding a test and changing the code.
* Submit a pull request.
For the ajax data source thing, I would try to modify or extend the existing data source code to add the behavior you are looking for. As you mess around with it trying to figure out what you need to change, you will encounter the areas of the code that you need to understand.
With this sort of strategy you can avoid having to fully understand all the code while still being able to modify it. You might end up implementing stuff in a way which is not the best, but you will probably be able to implement it faster. It's the classic technical debt dilemma: understanding the complete codebase will allow you to design features that fit in better and are easier to maintain and enhance, but it will take a lot longer than just hacking something together that works.
Once I've found and fixed a few things, or if the code base is particularly small or clean that I can't find bugs to fix, I'll set about hacking in the feature I'd like.
I usually start by doing it in the most hacky way possible. That sounds like a bad approach but it narrows the search of how to implement it and means I'm not constraining myself to fit the code base that I don't yet appreciate.
In hacking that feature I'll often break a few things through my carelessness. In then trying to alter my hacked approach so it no longer breaks stuff I'll become more aware of the wider code base from the point of view of my initial narrow focus. This lets me build up the mental model.
Eventually I'll be comfortable enough I can re-write the feature in a way more consistent with the wider code base.
I don't normally start by trying to "read all the code" because that guarentees I won't understand much of it (I'm not quick at picking up function from code). I might have a skim if it is well organised, but I find the "better" written a lot of stuff is, the harder it is to grok what it is actually doing from reading it. to me, reading good code is often like trying to read the FizzBuzz Enterprise Edition[1].
I've worked on many legacy systems: I was last year implementing new features into a VB6 code base, this year (at a different job) I am helping migrate from asp webforms to a more modern system. I've found that starting with trying to fix an issue to be the best way to dive into the code base.
Use good source control so you're never "worried" about changing anything or worrying that you might lose your current state. Commit early, commit often, even when "playing around".
[1] https://github.com/EnterpriseQualityCoding/FizzBuzzEnterpris...
Good luck.
> 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.
My comment from that thread:
I do the deep-dive.
I start with a relatively high level interface point, such as an important function in a public API. Such functions and methods tend to accomplish easily understandable things. And by "important" I mean something that is fundamental to what the system accomplishes.
Then you dive.
Your goal is to have a decent understanding of how this fundamental thing is accomplished. You start at the public facing function, then find the actual implementation of that function, and start reading code. If things make sense, you keep going. If you can't make sense of it, then you will probably need to start diving into related APIs and - most importantly - data structures.
This process will tend to have a point where you have dozens of files open, which have non-trivial relationships with each other, and they are a variety of interfaces and data structures. That's okay. You're just trying to get a feel for all of it; you're not necessarily going for total, complete understanding.
What you're going for is that Aha! moment where you can feel confident in saying, "Oh, that's how it's done." This will tend to happen once you find those fundamental data structures, and have finally pieced together some understanding of how they all fit together. Once you've had the Aha! moment, you can start to trace the results back out, to make sure that is how the thing is accomplished, or what is returned. I do this with all large codebases I encounter that I want to understand. It's quite fun to do this with the Linux source code.
My philosophy is that "It's all just code", which means that with enough patience, it's all understandable. Sometimes a good strategy is to just start diving into it.
Wide inheritance and macro usage are probably the worst. Good naming can aid understanding, but basic things like searchability are harmed by this.
Of those two, macros are the most trouble. You can't take anything for granted, and must look at every expression with an eye for detail. Taking notes becomes essential.
Find an entry point to the system, then make it compile, then make the test run, then just keep on nudging the code until I'm satisfied I've covered what I'm interested in.
If I stay true to my mantra "only add test code when it is absolutely necessary" (is this argument needed? pass null and find out), I find an accurate (albeit not pretty) description the flow through that procedure.
Then you commit your test and save your discovery for posterity.
If the problem is some bug and there are stack traces that is my starting point, debugger and a few breakpoints chosen from the trace and then follow the stack and from there I start knowing how it is structured, and then the next bug and so on (fixing them of course) For code where I need to add features things get a little more tricky, but there is always some entry point, a web-service invocation, some web page, and try to understand what it is currently doing, again using the debugger to follow the calls and how the data is changed (sometimes even going into libraries).
Reading the docs if there are any is also a good place to start.
Once again, use the debugger a lot, makes it easier to understand than just reading the code.
(edit: formatting)
Every code base takes time to digest all the information. Sure the information passed your eyes, but is it committed to memory?
I use a large format (8x11 inch) notebook and start going through the abstractions file by file, filling up pages with summaries of things. I'll often copy out the major classes with a summary of their methods, and arrows to reflect class relationships. If there's a database involved, understanding what's being stored is usually pretty crucial, so I'll copy out the record definitions and make notes about fields. Call graphs and event diagrams go here, too.
After identifying the important stuff, I read code, and make notes about what the core functions and methods are doing. Here, a very fast global search is your friend, and "where is this declared?" and "who calls this?" are best answered in seconds. A source-base-wide grep works okay, but tools like Visual Assist's global search work better; I want answers fast.
Why use pen and paper? I find that this manual process helps my memory, and I can rapidly flip around in summaries that I've written in my own hand and fill in my understanding quite quickly. Usually, after a week or so I never refer to the notes again, but the initial phase of boosting my short term memory with paper, global searches and "getting my hands to know the code" works pretty well.
Also, I try to get the code running and fix a bug (or add a small feature) and check the change in, day one. I get anxious if I've been in a new code base for more than a few days without doing this.
Something that compliments that approach is in-code annotation. Recently, I've recently been trying out https://github.com/bastibe/annotate.el which is pretty sweet. Check it out!
I've often been dropped into codebases where there is only a month to question the previous maintainer before all the business knowledge is lost as they move on to bigger and better things. So getting all the questions/queries down asap is the fastest step to get the undocumented business logic documented.
Even when you can't ask the questions I like to turn all the unknown unknowns into known unknowns. :)
A list of the kinds of broad abstractions to look for might be useful;
* Each module and it's purpose
* Every global resource (whether global variables, message names, anything that the entire system has to deal with).
* The "style" that each coder used. Even "terrible" programmers tend to have a consistent approach and understanding that approach can make code much less opaque.
I also like to page though documents more quickly than my conscious mind can follow so as to get an unconscious feel for a code base. That might be just me.