After joining PSPDFKit, I was lucky enough to dive into a bunch of debugging sessions. However, only some were successful, and of those, most were backed by the same principles. So in this post, I’ll attempt to outline said principles, which will come in handy the next time I need to debug something. Along the way, I’ll share the story of how I solved a particular issue: UITextView flickering.

Frustrating smile

Early on in my career, I wanted to become a game developer. In my opinion, game development has some of the most hilarious bugs across all software industries. For example:

• There are hard-to-notice bugs (from @aaronzbest(opens in a new tab))
• And there are rather subtle bugs in physical engines (from @foosel(opens in a new tab))

Alas, iOS apps are usually prone to standard problems that aren’t so amusing, such as non-responsive user interfaces (UIs), stale data, and, of course, neverending crashes. They’re extremely annoying for both users and developers, and rarely are they amusing,

However, recently, I encountered something unexpected — something that got a frustrated smile and an “Oh, wow!” exclamation from me. Here’s a video of the unexpected behavior in action. In the video, the caret jumps all over a text field without a user’s participation.

Of course, there’s nothing funny about this for our customer. But now that the fix is out (12.2.0), it’s a good time to collect my thoughts and share the debug chronology of this out-of-line issue.

Setting the stage

Before jumping in to the debug techniques, one might ask: “What on earth text fields are even doing in PDFs?” Well, that’s an excellent question! Before joining PSPDFKit, I’d imagined PDFs as images and texts. And, for the most part, they are images and text. However, there are other parts that do totally wild things. For example, PDFs can carry all kinds of annotations, audio, and even video. 🤯

Returning to text fields, they’re part of PDFs referred to as forms. Forms in PDFs are somewhat similar to web forms (you know, name/email/password fields). Thus, from a user’s perspective, forms are rather straightforward. The implementation, on the other hand, is packed with intricate logic. Forms might interoperate with JavaScript, they might affect document representation (for example, hiding or showing certain parts of it), and much more.

If you to know more about forms and how to use them, refer to our introduction to forms guide.

Text view and forms

In general, forms are built from a predefined set of controls, like text fields and checkboxes. The same set of controls is also available on iOS. Alas, most native controls require some finishing touches before they can function in a PDF forms context.

UITextView is a prominent example of a native iOS control that requires many finishing touches, specifically when it comes to its relationship to UIScrollView. The following is an example of some things that require careful consideration:

• Even though UITextView is a UIScrollView subclass, text becomes blurred when you try to zoom in on it(opens in a new tab).
• UITextView’s caret tracking isn’t optimal, but it becomes weirder when UITextView is placed inside UIScrollView.
• Automatic font scaling doesn’t support the entire range of PDF text formatting options.

The list goes on and on. We tend to stumble on new edge cases even after 10 years of fusing UITextView with UIScrollView.

Starting out

Debugging sessions are reminiscent of a gradient descent, in that the goal is to narrow a problem’s scope with every step. Each step usually involves the following phases: research, formulating a hypotheses, rejecting or proving the hypotheses, and planning next steps with new information.

Before starting out debugging, I tried to reliably reproduce the problem and outline the reproduction steps. In this case, the customer who reported this issue kindly provided a video with reproduction steps and a sample document that reproduced the problem. That’s a welcome shortcut and outrageous cheating, but I’ll take it.

Ideally, one would reproduce the problem in a regression test. I didn’t, and I regret it now, because it would’ve saved so much time.

Next, I began gathering as much information as possible about the problem at hand by asking myself a series of questions, including:

• What views are onscreen when the problem surfaces?
• Can it be reproduced in the iOS simulator?
• Is it a regression?
• Does the bug happen only on specific set of devices?

Having a predefined list of icebreaker questions streamlines this part. It also provides hints about possible information sources. Maybe you have remote logging, maybe your crashes have breadcrumbs, etc.

It also helps to write down the answers.

Debug journals

I have to confess, I used to hate debugging. It takes time, it takes lots and lots of effort, and you might run into Apple frameworks that are close sourced. Combine thee points, and it doesn’t sound particularly inspiring. I also used to think that it’s a one-shot process; it’s like a game without saves, and you either find a bug’s cause, or you die and start anew. A bug’s context erases from memory with time.

This is where debug journals come into play. For me, keeping notes while debugging is crucial. Yes, journals doesn’t magically solve everything, and debugging still requires lots of work, but now, at least there are checkpoints.

So, the way I debug is by asking and answering questions in a journal, which, for me, is a plain text file. Here’s an example from the flickering cursor issue:

Document flickering when zoomed in on text field entry · #36018 (keeping the issue’s number as a search reference)
-  [x] Does it reproduce on iOS 14?
-  Yes.
-  [x] Does it reproduce on iOS 15?
-  Yes.
-  [x] Can it be reproduced in `FormTests.pdf`?
-  Ah, nope. The next idea is to extract that specific form to a new document.
-  Forms are like annotations, so I can probably grab a single element and add it to a freshly created document. 🤔
   -  [x] Can it be due to a view hierarchy difference?
          ...
-  [x] Can it be connected to the text view’s font?
-  Nope, the default font also causes bouncing.

And so on…

I usually end up with a long list of questions and answers I sift through. They help me quickly form and validate my next hypothesis. And, because I have all the notes, I can always leave a problem for later without losing my progress.

Diving in

Okay, getting back on track. After loading a sample document and checking Xcode’s Debug View Hierarchy tool, it became apparent that the problem was somehow related to scroll views — specifically, one of our private UIScrollView subclasses. So I made some notes in the journal:

-  It’s somehow related to `PSPDFAvoidingScrollView`.
-  Does any class’s logic affect the scroll offset?
   ...

I stumbled upon the overridden -[PSPDFAvoidingScrollView setContentOffset:animated:] method, along with a bunch of methods that affected scroll offsets. I then commented them out or replaced them with no-op actions. The problem persisted. So, I concluded that it’s not something in PSPDFAvoidingScrollView, but rather in other classes that use it:

-  It’s somehow related to `PSPDFAvoidingScrollView`.
   ...
-  The problem still reproduces even after commenting out everything from `PSPDFAvoidingScrollView`.
-  Does it have anything to do with clients of `PSPDFAvoidingScrollView`?

There were at least three places that popped up in setContentOffset stack traces. I went through them one by one, noting them down, commenting them out, and checking whether the problem reproduced. The journey wasn’t that smooth, and initially I stumbled down a wrong path, but I’ll spare you the boring parts.

Eventually, I determined that one of the callers of setContentOffset propagated suspicious values to the scroll view:

-  `PSPDFTextView` somehow influences the `PSPDFAvoidingScrollView` offset.
-  `-[PSPDFAvoidingScrollView setContentOffset:animated:]` gets a legit frame and the next one is scrambled up:
-  That’s the correct origin (x = 1405.5643702027589, y = 1019)
-  That’s the scrambled origin (x = 136.00433972557607, y = 1019)
-  It causes bouncing.

In the first call, the x origin was 1405, but in the second call, it was 136. This is a big difference. So somewhere when setting the content offset, the x origin value was incorrectly calculated, leading to the bouncing. This value came from another private class, PSPDFTextView. I was slowly circling in on the problem.

After replacing PSPDFTextView with a plain UITextView, the problem… didn’t go away. 😬 I’d ended up with a plain UITextView that was passing fancy offsets to a plain UIScrollView. There was only UIKit in stack traces. It surely sounds suspicious. It’s almost like blaming a compiler for errors. So, I summarized the findings, and then I cried out for help.

Pairing up

Like everything, pair programming has its own pros and cons. However, when it comes to debugging, I find it hard to pinpoint the right moment to pair up with someone. On one hand, together there’s a chance of resolving problems more quickly. Alas, debugging is usually time consuming, so, pairing up means spending twice as much time on something.

At this point, though, I realized I wouldn’t mind another pair of eyes on the code. If my conclusion were true, we would’ve needed to look into UIKit internals, which means disassembling UIKit. I’m far from an expert when it comes to disassembling and spelunking. Thankfully, my team is quite well versed in it. Long story short, Douglas (my team manager) and I jumped on a call to make sense of my findings.

It took literally two questions and a quick glance at a method from the stack trace, -[UITextView _scrollRect:toVisibleInContainingScrollView:], to figure out what was going on.

Our findings

The gist is that, for some reason, UITextView tries to adjust the visible area of its parent scroll view: UITextView tries to highjack its parent, UIScrollView.contentOffset, given certain conditions. It works fine until a parent scroll view is zoomed.

The behavior is caused by textView.scrollEnabled = false. With disabled scrolling, -[UITextView _scrollRect:toVisibleInContainingScrollView:] starts adjusting the parent scroll view.

Remember PDF forms? Their elements also have setting flags. One of them is 🥁 doNotScroll 🥁. doNotScroll can be set on text form fields, determining whether text in a form field can be scrolled or if it should stay fixed. If this flag is set, we propagate this to the UITextView. That’s where textView.isScrollEnabled was getting its value from.

Solution

If your app has an editable UITextView embedded in a UIScrollView, make sure that the text view’s scrolling is always enabled, e.g. textView.scrollEnabled = true.

If you need to prevent scrolling in text views contained in scroll views, set text views’ frames to match their content programmatically — for example, by calling NSAttributedString.boundingRect(with:options:attributes:context:) and updating a text view’s frame accordingly.

We also added a regression test. It’s a UI test that zooms into a text field with disabled scrolling, enters a text, and observes for UITextSelectionDidScroll notifications. This internal UIKit notification is fired whenever UITextView tries to adjust its parent’s content offset.

Conclusion

In general, before you dive into a problem, try to come up with clear reproduction steps. Chisel away at the part in question and see whether the problem still reproduces. Ideally, you should end up with a minimal reproduction example. It can even be a standalone Xcode project or a Swift Playground.

Additionally, consider keeping a debug journal! It’s a place for internal conversation. What’s more is it helps to preserve and share knowledge. Imagine instead of saying, “Yeeeah, I’m still working on the bug,” you can provide a decent report with your ongoing progress.

Don’t be afraid to ask for help. It might be someone from your team, it might be the future you (take a break for a day), or it might be a rubber duck. Sum up current findings to clarify the situation.

You can find more debugging tips in The Pocket Guide to Debugging(opens in a new tab) by the amazing Julia Evans(opens in a new tab).