Learning by reading other people's code

I’m not really a very good developer. I suck at maths. And if you asked me to implement a binary search tree, I would probably struggle. (OK, if I had a little bit of advance warning, I might cheat and look it up in a book first.)

But, I think I’m quite good at searching, and finding solutions to problems.

When I’m stuck on coding problems, I usually turn to the experts and try to stand on the shoulders of giants.

This is not because I’m lazy, or a copy-paste developer. It’s because I tend to believe that someone has probably already solved a problem before me and, more importantly, they’ve probably done it better. I don’t want to try to solve the same problem again.

In practice, this usually means learning by reading other people’s code. So how do we find this code?

Using the Google machine

My first port of call is usually to Google Search, to find code examples. I’m often looking for examples of how I should configure a particular component, or interact with a certain API. Google Search is surprisingly good for finding these things!

In the past, I used Google Code Search, which was a dedicated code search engine. After it was discontinued (it’s since been nicely open sourced), I wondered how I was going to search for code on the internet.

But the closure of Code Search happened at the same the time as the rise of GitHub as the dominant open source project hosting platform. Almost everyone hosts their open source project there now. This dominance, plus GitHub’s excellent coverage in the Google index, and the continued strength of the open source movement, means that it’s now pretty easy to just use a plain Google search to find code.

GitHub has its own search engine, but it doesn’t yet match the power of Google. With Google, I can use phrases and exclusions to really find the code that I want.

I usually start with plugging something like this query into Google:

site:github.com hibernate

This will look on GitHub for files containing the word hibernate. If I want to narrow it down a bit further, then I add inurl:<pattern> which restricts the files returned to only those which match a certain string.

This is really useful if, for example, I want to search for .java files only:

site:github.com inurl:java processor

Now Google will only return URLs which contain the string java. (This is usually a good indicator that it’s going to be a Java source file.)

Note that this query works really well today in 2019 because GitHub is currently the number one place for project source code hosting. If the ecosystem becomes more fragmented, and projects move to other platforms, such as GitLab or Bitbucket, I would start to searches those separately, too.

Unit tests

The second place I usually look is in the unit tests for projects that I use.

Have you ever looked at the unit tests for your favourite module or framework? I’ve found it to be a goldmine of information about how it works.

Often, open source documentation is not great (usually because developers are too busy working on new features and fixing bugs to spend time on the docs), so diving into the code is a really good way to understand how the developers intended for the component and its features to be used.

An excellent example of this is Apache Camel. In addition to the complex core functionality within Camel itself, there are now almost 300 components. This means that there are 300 modules which each need to be documented. Sometimes there just isn’t documentation for everything.

So if I’m using an unfamiliar component in Camel and I want to know how it works, I often go to the unit tests.

For example, when I started using the MongoDB component, I wanted to know how I could build up queries to send to Mongo. So, I scoured the unit tests, and I found a unit test in the source code which shows how to find an object in Mongo using a query. This means I found a tested piece of code which achieves exactly what I want to do. Result!

To find unit tests, just look up your project on GitHub, navigate to the module or subcomponent you’re using, and have a browse around the src/test/java directory. You’ll certainly find some useful stuff.

Get researching

So what’s missing? I’m probably missing the behemoth in the room – Stack Overflow. But I’m less keen on SO, because the answers are often posted without any context. This means it’s hard to see whether a solution fits in the same problem space as yours.

So there we go. Google searches and code readings for your problems. Next time you’re stuck, give them a try.