Grokking Your Terrain

When you’re working with a small codebase, given enough time, you’ll come up with a decent map of how everything fits together in your head. If you have to add a new feature or debug an issue, you’ll likely have a good hunch of where in the code to start.

As the complexity grows, it becomes impossible to keep that mental map up to date. Furthermore, as your team expands, it’s important to make sure that everyone has context during discussions involving code, as well as a handy resource for exploring all the work that’s already been done.

Enter OpenGrok

Main Page

OpenGrok is a powerful solution to this problem. It provides you with an extremely fast web interface (or, ‘A wicked fast source browser’, as deemed on the project’s page) that allows you to search across or browse all the projects that you index into it. Assuming you use one of the many compatible version control systems, it also lets you view the history of your code, making it trivial to discover where a suspected issue might have crept in. If your code lives in some unsupported version control, you might not be as out of luck as you’d think - OpenGrok is open source, with a thriving community that’s happy to help you write a plugin for your svn of choice.

Deploying OpenGrok

At Flatiron, our preferred deployment system for projects is Ansible. As such, for our internal deployment, we wrote an Ansible role based on the deployment documentation provided by OpenGrok. The documentation is fairly thorough, and the process itself is straightforward. We suggest following the wiki, making adjustments if necessary.

Mapping Your Terrain

The only thing left to do is to tell OpenGrok what code you want indexed by pulling it down into its source root folder. We suggest automating the pulling of the code (perhaps using Ansible?) on a nightly basis, if not more frequently.

Reaping The Benefits

Beyond the obvious, OpenGrok can also be used to improve productivity for a multitude of tasks, such as:

  • Unifying the codebase: By abstracting away details such as the version control system, it gives you a single interface to browse your code.

  • Browsing the history: You can also examine the checkin history of your entire repo, or of a specific folder or file, along with having the ability to diff any two commits at will.

History

Diff between images

  • Refactoring code: By doing a simple symbol search to lookup wherever a piece of code is being used, you can find out the impact of a refactor instantly. For example, if I needed to refactor the setDefinition method in my project, I could just do a symbol search for it to find all its occurrences, giving me a list of every place that might need to be touched.

Symbol Search

  • Contextual conversations: By letting you share a link to a direct line of code in a file, it makes it easier to keep everyone on the same page, which is especially helpful when debugging a problem.

Direct link to line of code

  • Security Sweeps: Along with helping you look for vulnerabilities in your code (by letting you search for all usages of a library that just had a vulnerability reported in it, for example), it also lets you do a periodic scan of your codebase for more obvious vulnerabilities, such as plaintext passwords being checked into your source.

Password search

  • Code Reuse: One of the biggest benefits is that it lets you search for existing implementations of things you might otherwise end up rewriting. There have been several occasions I’ve been saved from reinventing the wheel because of a simple search on OpenGrok.

So go ahead and dive into your code. In other words, start grokking!