When on the hunt through npm packages, github repos and random blog posts, there’s really one question worth answering before diving into the particulars of a library: Is this worth the time and investment that comes with a deep reading of the codebase?

With a heavy nod to the Mortimer Adler’s “How to Read a Book”, I’m going to offer a quick guide for doing an inspectional reading of a codebase. A reader should be able to ascertain whether the code warrants a closer investigation and possible adoption.

So, let’s try some things!!

Name

The first and most obvious clue. A badly named package rarely receives a sympathy click. Sorry.

File structure, highest level

This is a like a weird table of contents with hidden surprises lurking underneath. The shame of it is, the top level might not tell you the entire story, and could lead to some disconcerting deep exploration where you really want to keep things superficial. A browsing of the first two levels folders will give a good overview of what you’re dealing with.

package.json

I would call the package.json a strange hybrid of an index / bibliography. It can be sort of useful to see what packages the current library depends upon, what’s even more useful is the scripts section. This can show the paths into what type of testing is performed, and might also be a gateway into any compile or build steps. In essence, what else does the author expect this library to do? This will give some clue, but not enough, I think, to draw conclusions on it’s own.

README.md

This should solve the general question of “what problem is the author trying to solve?” This question is of critical importance to any potential user. This is akin to an author’s note or introduction to the library. Something well written is going to give installation instructions and perhaps some documentation of the library API, if it exists. After reading this, you should have a firm idea of why this library exists and how to begin using it.

Changelog.md, releases (in github)

This is mostly useful when updating a library upon which you already rely. Think of this as the notes to the second, third, fourth edition, etc. A well done changelog can show a user entry points into a deeper understanding of specific issues the library attempts to address.


This post’s book: How To Read A Book