What the heck does this code do? Find out before you refactor

A common problem for developers is being able to work effectively with and understand large code bases. This problem can affect everyone on a team, whether you’re new or experienced. It’s hard to know every line, and everyone needs to find their way around the code base.

Better not refactor!

Refactoring JavaScript code can be intimidating, so many developers avoid it. Over time, they write code to fix bugs and implement features, and the code base grows. As it grows, it becomes harder to maintain. At the same time, team members with tribal knowledge leave and others come on board. The technical debt grows and grows.

Orion to the rescue

Imagine that you’re browsing a code base and you see a function call. You might ask yourself:

“Where is this function defined? Are there multiple declarations? Who else uses this thing? If I change the implementation, who is affected?”

Fortunately, Orion has a new feature to help in this scenario. It’s called “References.” To use it, click a code element, such as a function call, and select an option from the References menu:

Web IDE with References menu selected

A window opens to show each match, categorized and weighted:

References window, showing categories


In the window, you can browse by category to focus on the most important matches first. For example, “Function Declarations” and “Function Calls” are important and interesting categories. If a category doesn’t contain any matches, the category is not shown. All matches are categorized, including those that occur in comments and strings. In JavaScript, strings can be evaluated (don’t do this) and JSDoc contains valuable information.


Orion includes a type-inference engine that can determine the type and scope of a function or variable. This information is used to weigh the results.

Here is a handy legend:

  • Green check mark: Perfect match
  • Blue question mark (?): Potential match
  • Red (x): Not a match

Go ahead and refactor

It’s no accident that the user interface (UI) for the References feature looks like the UI for the Global Search feature. When you’re wondering how a function is used, you need to see the calls and declarations, but you also need more information. JavaScript is a dynamic language where strings can be evaluated and functions can be saved in properties and then called or even passed around as arguments. A function can be used in meta programming; you need to be aware of that when you refactor.

You can refactor the references that you found to the main() function to be main2() by clicking Preview:

References window, showing replacements

A simple rename consists of these actions:

  1. Finding all of the references
  2. Inspecting each reference by category, noting any checks and question marks
  3. Selecting or clearing the replacement check box
  4. Clicking Replace

Of course, refactoring is more than renaming, but the first step is to find and categorize each match.


You can use the new References feature in Orion to understand how a variable or function is being used. Understanding the code is the first necessary step towards refactoring.


This entry was posted in General. Bookmark the permalink.