A lot of things like presenting changes in the form of diffs (generally unified diffs these days, fortunately). Some of the time when I'm reading these diffs in various contexts (eg), I've felt that I was struggling to fully understand what I was seeing. Today, I had a realization about this that feels completely obvious in retrospect, namely that understanding diffs relies on implicit contextual knowledge of their surrounding code. Most of the time, to understand the change that a diff is making you need to mentally reconstruct an image of the code being modified, in much the same way that indirect manipulation UIs require you to construct mental context.

When you already know the code well, this is easy; you can readily 'see' both the before and the after version of the code. But if you don't really know the code and are reading it cold, this is a much harder thing to do. You don't have a clear mental image of what's going on and it's much harder to see and reason about the effects of the change, unless they're obviously and strictly local ones.

Unified diffs provide some obvious context, but generally not all of the function or other entity that the change is embedded in. Even when they do show everything, a diff is a compact encoding of a change and properly understanding the change requires imagining and to some extent understanding the before and after versions. I'm not sure there's any clear way to present this inline in text; I think the most comprehensible way of showing diffs will always be side by side (ideally in a graphical environment).

Realizing this makes me understand why I often struggle trying to make sense of a fair number of the diffs I read, because I'm often reading changes in codebases that I don't know (sometimes even in languages that I only partially understand). Probably I should see if I can easily use tools like kdiff3 when I'm picking my way through other people's code.