Wild #imports: How to Tame File Dependencies 

 November 6, 2011

by Jon Reid


Like all C-based languages, Objective-C files usually come in pairs: there’s a header file, and an implementation file. Either can use the #import directive to include other header files. And if you’re not careful, it’s easy to create an explosion of file dependencies. What are the consequences? How do we tame #import dependencies?

[This post is part of the Code Smells in Objective-C series.]

Code snippet sample

Improve your test writing “Flow.”

Sign up to get my test-oriented code snippets.

File Dependencies

Unnecessary #imports in a .m file are a nuisance. Why? Because it forces you to have those other files in your project. This isn’t a big deal when you’re working on a single project, but immediately causes trouble when you start a new project and want to reuse some source files.

But unnecessary #imports in a .h file are even worse: the problem grows exponentially! That’s because a header imports another header, which imports another header, and so on. Think of it as a dependency graph:

Dependency graph

Say A.h imports B.h and C.h. But B.h also imports D.h. So to add A to your project, you have to pull in B, C and D as well. And this graph is about as simple as it comes. If unnecessary #imports aren’t kept pruned away, the dependency graph will get out of hand.

Problem: Incremental Build Time

File dependencies also affect incremental builds. Touching D.h causes Xcode to rebuild D.m, B.m and A.m. If you’ve only worked on small projects, it’s no big deal. But trust me on this: on a large project, things can bog down. I’ve had people tell me, “This isn’t important. I need to take a short break anyway, so I don’t mind waiting while it builds.” But folks who say that aren’t doing test-driven development. In TDD, unit tests give feedback about the code you just changed. The more you can tighten that feedback loop, the more you can stay “in the zone.” Even a few seconds can make a difference.

Problem: Hidden Dependencies

While untamed #imports in header files affect build time, don’t think that implementation files are off the hook! The dependency graph is still at work, though in a less obvious way.

Let’s refer to the same graph, but change things around a bit. Say A.m imports B.h and C.h. But B.m imports D.h. The problem here isn’t that touching D causes too many modules to recompile. The problem is that to include A in your project, you have to drag along B, C and D as well. You can scan A.m to find the first level of file dependencies by reading its #import directives. But the dependency on D is hidden. You won’t discover it until you add B, and the build fails.

Trying to add a single module A can quickly become an exercise in frustration, as you chase down successive levels of the dependency graph.

Code Smell: Too Many #imports in .h

So let’s look at how to tame file dependencies, first in header files, then in implementation files. Starting with header files, the code smell to look for is simply: too many #imports. Let’s consider which #imports are necessary, and which we can avoid.

Say we’re defining a class Foo. It inherits from Superclass, and implements two protocols:

@interface Foo : Superclass <Protocol1, Protocol2>
// ...

It’s necessary to #import the headers that define Superclass, Protocol1 and Protocol2.

But what about objects that are instance variables or properties? What about other protocols? What about objects passed as arguments, or returned by methods? Let’s fill in the contents of Foo’s declaration:

@interface Foo : Superclass <Protocol1, Protocol2>
    Bar *bar;
@property(nonatomic, retain) id <DelegateProtocol> delegate;
- (void)methodWithArg:(Baz *)baz;
- (Qux *)qux;

We’ve added references to Bar, DelegateProtocol, Baz, and Qux. How many declarations do we need to #import for all these? Answer: None! All we need is to forward-declare them before the @interface:

@class Bar;
@class Baz;
@class Qux;
@protocol DelegateProtocol;

Some like to combine all @class forward declarations on one line, but I prefer one per line. It lets me sort them, which in turn helps me find any duplicates. Also, doing one declaration per line reveals just how many there are.

Note: For classes from built-in frameworks such as UIKit, just #import the framework and don’t bother forward-declaring each class. A framework comes as a single prebuilt chunk with a master header, so it doesn’t affect file dependencies at the same granular level. This is a good rule to follow for any frameworks and libraries, unless you create a particular library as part of your build process.

…Getting back to our example, the only headers we need to #import are those that declare the superclass we’re inheriting, and the protocols we’re implementing:

#import "Superclass.h"
#import "Protocol1.h"
#import "Protocol2.h"

There may be other non-object declarations we need to bring in, such as enums and typedefs, but as a general rule, having any other #imports in a header file is a code smell.

This is also why I isolate protocol declarations in their own headers instead of lumping them in with the classes they cooperate with. It keeps the dependency graph pruned.

Code Smell: Too Many #imports in .m

Forward declarations are infrequent in implementation files, because we’re usually sending messages to objects, not just passing objects around. (Though if your class is the middle-man of a delegation, you will find times when a method takes an argument from a return value and passes it back as its own return value. Then see if you can use forward declaration and avoid the #import.)

So we usually can’t use forward declaration to trim #imports in the .m file. But in both .h and .m files, #imports tend to accumulate over time. It’s not hard to have #imports that are simply unnecessary and can be deleted outright. This happens when:

  • You add certain #imports by habit when starting a new class because they’re part of your regular toolkit. But you never actually use every tool.
  • You remove an object reference from your class. But you never go back and remove its header.

Basically, it’s cruft management. An occasional clean-out of crufty #imports can trim unnecessary file dependencies. In a coming post on #import completeness (the opposite of having too many), I’ll share why #import order matters.

But even if you drop all unnecessary #imports, you can still end up with one #import after another in a long list. In the heat of development, it’s easy to lump more and more stuff into a class. Cohesion goes down (because the class is doing too many things), and coupling increases. The result is a horrible dependency graph.

In Martin Fowler’s Refactoring book, he describes a code smell called Large Class, where the indicator is too many instance variables. I’d say too many #imports is another indicator of the Large Class smell. (It follows that too many forward declarations is also an indicator.) Follow the Large Class recommendation: use the Extract Class or Extract Subclass refactoring steps to break things up. You’ll be pleasantly surprised at the difference! “High cohesion” will change from a theory, to something you can actually feel.


Let’s bring it all home! Here are the things to look for to manage file dependencies:

#imports in header files:

  • #import the superclass you’re inheriting, and the protocols you’re implementing.
  • Forward-declare everything else (unless it comes from a framework with a master header).
  • Try to eliminate all other #imports.
  • Declare protocols in their own headers to reduce dependencies.
  • Too many forward declarations? You have a Large Class.

#imports in implementation files:

  • Eliminate stale #imports that aren’t used.
  • If a method delegates to another object and returns what it gets back, try to forward-declare that object instead of #importing it.
  • If including a module forces you to include level after level of successive dependencies, you may have a set of classes that wants to become a library. Build it as a separate library with a master header, so everything can be brought in as a single prebuilt chunk.
  • Too many #imports? You have a Large Class.

OK, go check your code! I’m going to check my own code, because I know there are things I’ve missed. Let’s tame those wild file dependencies!

Question: What discoveries did you make as you examined your code’s file dependencies? Leave a comment below.

[This post is part of the Code Smells in Objective-C series.]

Kent Beck Inspired Video: Oh, the Methods You'll Compose!

Jon Reid

Programming was fun when I was a kid. But working in Silicon Valley, I saw poor code led to fear, with real human costs. Looking for ways to make my life better, I learned about Extreme Programming, including unit testing, test-driven development (TDD), and refactoring. Programming became fun again! I've now been doing TDD in Apple environments for 20 years. I'm committed to software crafting as a discipline, hoping we can all reach greater effectiveness and joy. Now a coach with Industrial Logic!

    • Jianhua, that’s a great question! Unfortunately there doesn’t seem to be a good solution at present for Xcode developers.
      A heavy-reading book on the topic is Large-Scale C++ Software Design by John Lakos. He offers a detailed analysis, including mathematical models for measuring when dependencies become too much.
      cppdep is a project based on the book. I tried altering it today to look at .m files, but couldn’t get it to work.
      Ideally, an Xcode-specific tool will examine the project settings. Hmm, you have me thinking about working on this…

  • Very nice post, Jon. This confirms what I usually do with my design. And that’s good news. Will go read up Large Class in Refactoring that I bought last year. But before I do, I am thinking “factory method”..

    – Herman

    • Herman, Large Class is one I see often. People rarely set out to write a Large Class. It happens gradually. There’s a lot to learn from the list of code smells in the Refactoring book!

  • That’s why I love the IDE Appcode so much. It has great features like color coding the #imports which are unnecessary and an optimization tool for imports.

        • AppCode adds a new level of productivity to objective-c development, so I clearly can say yes. It’s not supposed to be a full replacement for XCode but clearly it is for writing code. It doesn’t provide any means to edit the project file nor interface builder files. The same project can be open in both applications without any trouble.

  • Thanks, great article!
    I have a question though. You mentioned the importance of the order of #imports. Could you elaborate a little about that, how do you sort your #imports ?

    • Nice example, Alex. As you say, the difference isn’t noticeable on very small projects. I think this lulls people into thinking everything is fine. I’ve spent many years working on large projects, where incremental compilation time can matter a great deal! I’m eager to shave even a small amount of time on a large project, knowing that it will help the other developers stay “in the flow” instead of saying, “Well, I guess I’d better take a coffee break while I wait for this.”

  • {"email":"Email address invalid","url":"Website address invalid","required":"Required field missing"}