What are some good approaches for reading Javscript code?

Question

I'm looking for suggestions on how to read large Javascript codebases, for example, of a framework. For example, let's say P5js, but this applies to any large framework (i.e like AngularJS, Ember, etc)

My goal is to be able to look through a Javascript framework's source code and be able to understand what various functions do and how they work. I want to be able to investigate the inner workings of the framework and understand what its important objects and variables are.

The problem is that the files are so large, functions that are exposed through the documentation internally call several more layers of "private" functions, and an assortment of internal objects and data structures are referred to. This is true for most frameworks I've examined. On top of that, there are also events, watchers and other mechanisms that make it harder to track what is happening under the hood.

With Java, this was a lot easier for me - though still time consuming - because I could open the project in Eclipse and easily navigate through the call stack, call hierarchies, identify types, parameters, etc. With Javascript it just seems impossible.

So, what are some good techniques you could recommend for reading and understanding large (multi-thousand line) framworks, particularly in Javascript (though general cross=language techniques are also welcome)

Answer 1

Use tests.

I read code with my fingers. Print out code and hand it to me and I go cross eyed. Sure you can doodle on it, highlight it, annotate it, and draw cartoons in the margins but mostly, I run the code. I test.

Oh sure I can tell you what the odd hello world does. Maybe decode a 3 level deep if else maze. But read enough code and it bleeds together. I could put my faith in comments but the debugger has never lied to me. It has surprised the hell out of me, but never lied. So I run tests.

It helps to read the documentation occasionally but that really just helps me find the right things to call, inherit from, or ask to be injected into my tests.

If all that fails you can fork it and get your own copy of the code to run. Then you can go to town refactoring lengthy nonsense into succinct nonsense. Doing that always makes me feel good but mostly forces me to pay attention to what I'm playing with so I don't day dream of chimichangas. And if you're going to do that you need... tests.

Answer 2

CandiedOrange names the most important single tool for understanding code: the code itself. You can't always trust documentation, and anyway the docs are aimed at people who just want to use the public methods of the frameworks, so you have to run the code, inspect the values of variables or the return values of functions, and use debugging techniques to work out what's going on when the code isn't behaving the way you expect. That's exactly right.

But that doesn't offer much direction for a general approach to the code. Frameworks can vary in purpose and construction enough that no single piece of advice will apply in all situations, and what helps me understand code might not work for you, but here's what I would do when looking at a big, complex codebase:

1. Decide how much you really need to understand. Sometimes it's easier to just work around the code than to delve into its details, and there's no shame in writing code that solves the problem you actually have. If you really do need or want to understand more (e.g. if you're going to do development on the framework itself), then...

2. Look at the bottom couple of layers. If your framework makes network calls, then the bottom layers will probably build network requests. If it makes objects, then the bottom layers might deal with how objects are created, updated, and persisted. Understanding approximately how your high-level operations work at the lowest level can be very helpful.

3. Look at the top couple of layers. Very often an API will have a bunch of public methods that call a smaller number of private methods with some extra options set. A hypothetical framework with makeGreenBox and makeBlueBox methods that call _makeBox(color='green', ...) and _makeBox(color='blue', ...) would be a typical example. If you know how those work, you can take advantage of them when the public methods don't suit your needs.

4. If the framework is written in a way that makes sense to you, this is probably enough for you to have a good overview of how any single action works: "I make a request to foo which delegates to _bar with some options set, and ultimately it calls _makeThingy with a bucket of options and returns the result." Even if you can't do that every time, you should be in a good position to understand the general flow of the code.

5. Just start working with the code. You probably had some reason you wanted to understand the framework in the first place, and nothing will do you so much good as just starting to work with the code and seeing where you bump against sharp edges. Pain is how we learn. :)

Understanding absolutely everything about a single request sounds nice in theory, but as you've noted the call stack could be very deep, and there could be complex side effects. The power of abstraction is that we don't need to understand every line of code. It's enough to start out treating everything in the middle as a black box that does what it says it does, and then to inspect it in more detail when needed.

The upfront cost of understanding (say) a hundred-thousand line codebase is bigger than you're likely to want to pay, and it's probably not worth it. Approaching from the edges and working your way in as needed can get you conversant on the code in a matter of hours rather than days or weeks. You'll eventually learn the details if you keep working with it--and if you don't keep working with it, you've saved a lot of needless effort.