Sifting through your code base with ctags

By Gus in Development on January 08, 2018

Search key 770

Developers spend most of their time maintaining, debugging and adding features to an existing code base that they probably haven’t built.

It takes a whole lot of effort to get familiar with the code base, and things can get even harder if it’s a legacy code base worked on by many developers.

It’s the nature of code to get complicated over time and the addition of features and bug fixes will speed up this process. In fact, the more code you have, the more likely you will find bugs hidden in the shadows.

mar-newhall-226045

But, at the end of the day, it’s inevitable, you will have to write code. Having good development practices — such as code review, pair programming, common code standards within teams, and good test suites — is indispensable for a healthy code base.

Anything that makes coding easier and more robust can save developers time and product owners money. Find out about a tool that does just this.

The hunt

I’ve been working recently on a fairly large Ruby on Rails application composed of multiple internal and external gems, modules and classes, spread across several files. It’s challenging to navigate between these files, especially when debugging an issue.

Sometimes what I’m looking for is within the main code base. In this case a simple text search will solve the problem. But sometimes things are in different code bases. That’s where it gets complicated.

Looking through a shelf of library books. Debugging a distributed code base is like trying to find a phrase in multiple books.

It’s like having a few books that you’ve never read before, and trying to find a specific chapter. For books, you can easily use the index to find what you need. Wouldn’t it be great if we had such a thing for a code base? Something that lets you index all your methods, classes and modules and access them using a few keystrokes?

Thankfully there is a tool for this. It’s called ctags.

Indexing your code base

If you are familiar with IDEs like Eclipse and Visual Studio you probably know about their Intellisense capabilities, and features like accurate code completion and the ability to navigate to methods and class definitions in a few clicks.

With ctags you can pretty much have a similar functionality using a simple text editor. It’s a big time saver!

Installing ctags

This assumes you are using a Mac OS and brew.sh package manager.

Open your terminal and install the latest version of Universal Tags, which is the most recent and up-to-date implementation of ctags.

brew install --HEAD universal-ctags/universal-ctags/universal-ctags

Next, go to the Ruby on Rails project you want to index.

Run bundle install to fetch all dependencies.

And then run the following command:

ctags -R --output-format=json --languages=ruby --exclude=.git --exclude=log . $(bundle list --paths) -f .tags

This will index all your source code including your gem files.

Great! Now you should have a huge .tags file sitting inside your project.

If you are a Vim user, it comes with a built-in ctags integration. Open a Ruby file, position the cursor over a method and press ctrl-] to find its definition. See more commands here.

If you are a Sublime user, install this plugin and you are ready to go.

Congratulations, now you can easily find what you need!

Debugging tip

When navigating through files inside a gem, you will also be able to modify them. This can be handy when debugging, as you can throw some breakpoints. Just remember to take them out later.

It won’t save you from metaprogramming

Ruby is a very dynamic language and it comes with powerful metaprogramming capabilities. It gives you the freedom to define methods and classes at runtime, allowing you to produce flexible and scalable code.

Unfortunately, ctags only statically analyze your source code files. This means it won’t be able to find code generated at runtime.

Devise authenticate_user! method is a good example of this scenario. You won’t be able to find its definition because it changes based on your model name.

It not only increases your productivity, it also increases your programming knowledge

Ctags gives you a shortcut that seamlessly links your code base with external libraries. As this is all within your editor, it removes the extra step of opening Github in a browser to inspect a gem source code.

I personally love to use this when building integration tests. If I forget how to use Capybara helper methods I can get to the definition in just a few keystrokes. View a GIF demo of ctags in action.

As a developer I highly encourage you to every now and then look into a gem’s source code and understand how it works. You will often find code that does things you didn’t know were possible, code you don’t understand and patterns that you have never seen before.

It’s a great technique to discover more about the gem, as well as increasing your Ruby knowledge.