What It Takes To Grok Code

from WellFactoredProgramsCannotBeUnderstoodStatically, MarkAddleman wrote:

I think there are at least two dimensions to understanding code. One dimension is understanding the point of the code and why it is as it is. Even with VeryLongDescriptiveNamesThatProgrammingPairsThinkProvideGoodDescriptions, it?s hard to know why a piece of code exists in the first place. Is it an artifact of refactoring (such as a Visitor, a State, or a callback for DoubleDispatch)? Or, is it a piece of the domain? It is a partial pattern because the full one was too much?

Do all these "why" questions really matter ? To put that more precisely - if the code says "what" it is doing - its role in the computation - will knowing its origins yield any useful insights ?

The second dimension is about importance. Not every piece of code is as important as the other for the purposes of understanding what's going on (of course, every piece of executed code is equally important for the correct (or incorrect) functioning of a program). When I read code for the first time, or even code I wrote that has grown stale, I find that I unconsciously treat every piece of code with the same level of importance. This brings on the SevenPlusOrMinusTwo problem because I don?t know what to flush from my cache.

Do all these "why" questions really matter ? To put that more precisely - if the code says "what" it is doing - its role in the computation - will knowing its origins yield any useful insights ?

Yes, I think so. Not because it necessarily aids my understanding of what the code does, but it does help me accept the code as it is. I may be particularly hard headed, but when I see code that I don't immediately grok, I find myself challenging it. I ask questions like Why is that there? or How come they didn't use XXXX?

Oftentimes, this challenge is a useful part of my process of understanding the code. Of course, other times, it's just a waste of my time and energy, but I cannot seem to get to a point of understanding without going through this 'challenge' step.

A minor case to illustrate the point (The example isn't the greatest, but it's one that I came across recently):

 public void removeItem(String itemKey) {
    try {
       Item item = keyGenerator.getItemFromKey(itemKey);
       itemCollection.removeItem(item);
    } catch (NotFoundException? e) {
    }
 }

Of course, I don't need to know the answers to any of those questions before I understand what the code does, but will feel much more comfortable with my understanding if I knew the answers and thus its larger context.

-- MarkAddleman

 public void removeItem(String itemKey) {
    try {
       Item item = keyGenerator.getItemFromKey(itemKey);
       itemCollection.removeItem(item);
    } catch (NotFoundException? e) {
    }
 }

I would guess that this would be commented with...

    // We consider removal of a missing item to be OK.
    // (After the call, it's not there, is it?  ;-)

Your comments exactly illustrate my point: You cannot grok the above code without something else. If I StudyTheSourceWithaDebugger, I can grok it because because I see how it relates to other pieces of code. In fact, it is only used as part of a command pattern in the UI. Comments don't help, because I DontTrustComments?. Refactoring is only valuable AFTER I grok the code.

I disagree. I think a debugger can only help you understand the behavior, not the reason that behavior exists. The above snippet seems very clear to me: if the item isn't there, then an exception will be thrown, which is then squelched. I don't see how using a debugger would add anything to my understanding.

What's uncertain is WHY the exception is squelched. My guess was the same as a previous poster's: it's okay to remove an item that's not there. That's a guess, but a plausible one, and I don't see how a debugger would help me understand the 'why' any more clearly. --JimLittle

How about renaming things a little to make the intention clearer:

 public void removeItemSilently(String itemKey) {
    try {
       Item item = keyGenerator.getItemFromKey(itemKey);
       itemCollection.removeItem(item);
    } catch (NotFoundException? irrelevant) {
    }
 }

It seems to me that callers would be mainly concerned with removing an item, and that the silence is incidental most of the time. What removeItemSilently has in precision it lacks in intuitiveness, and I think one might get frustrated very quickly with having to specify an unimportant level of stealth throughout one's code. I would think comments would be better.

Here's how the debugger can help you:

Add a nonsense line of code in the catch clause, like "int x=0;" and set a breakpoint on it. Run the system. When you hit the breakpoint, you've found a case where the system is trying to remove an item that doesn't exist. Now you have a leg up on figuring out why the system does that.

In the absence of a complete set of unit tests that check every piece of functionality that the system possesses, the "why" question becomes very important: Otherwise, one might just remove seemingly useless code, and find that it breaks the system.

Do all these "why" questions really matter ?

Of course. In fact, that's the only good reason for commenting code. The code tells you the what, the comment the why. Thus you communicate to the human and the compiler the full extent of what is happening.

Do all these "why" questions really matter ?

If you want ot know why, ask the users. Don't expect the code to replace them. The source code only needs to document how it is doing things.

This page mirrored in WikiPagesAboutRefactoring as of April 29, 2006