The start of the school year — or “f’ing September,” as we tend to call it — is a brutal thing. Nothing not school related happens, and it has gotten worse over the years. This year, we had an exceptionally tough summer with some heavy infrastructural upgrades and network expansions/changes/reformulations, and none of it is known to work until you have a full student body using it.

As a side note — so far it’s going very well indeed. But I digress.

Needless to say, my already pitifully small number of posts became “no posts at all,” and that’s the way it was. Honestly, I’m in no position to pick back up (in part because I have a rather ambitious plan for online doings — no, it does not involve a Kickstarter — that will shape what my online life for 2013 and beyond will look like, and so this is not the time to redevote my scrivenorial efforts to essay-writing) anytime soon.

But I just had a discussion with a coworker that I absolutely needed to pass along to you, the folks who I like passing stuff along to.

The discussion was on a technique he used for commenting code, and through it composing and documenting code. And it’s brilliant.

And it would work for almost any form of writing, cartooning, or creative endeavor just as well.

More after the break. I’m Terry Gross, and this is Fresh Aire.

Code documentation is a crucial part of the process of programming. Code can look like an ungodly mess at the best of times — without a trail of bread crumbs to follow, you can get lost in your own code if you need to go back and bugzap. And God help the next guy if you don’t include copious comments in your code — if he’s good, he’ll be able to work out what you did, but he will lay a curse upon the next seven generations of your family in the process.

However, this coworker — we’ll call him Wes, because that’s his name — pointed out to me an essential difference between what comments in code should be and what everyone thinks they are. Most people think comments describe the function and purpose of the code. Hell, that’s the intuitive answer, right?

But they don’t. If they’re done right, your comments explain your intentions for the code block. And that’s a very different animal.

Code evolves, both upon creation and over the course of time. Often, that evolution will be in response to the natural disparity between what your program is supposed to do and what it actually does: all too often, programs function the same way as the infrastructural upgrades I referenced in the opening of this here essay — you spend a huge amount of time and effort planning, preparing, developing and executing your code, but until you actually have people using it in production, you’re not going to see where things break. When those break points — or ‘bugs,’ as the kids like to call them — show up, you have to go in and fix them. And sometimes that’s a fast fix, and sometimes it means fundamentally redeveloping the code. And in both cases? It’s the rare programmer who’ll keep his comments up to date and accurate. Often, there’s no damn time.

However, comments that explain the intentions for a code block are far less likely to go out of date, and are far easier to correct when they do. They explain what you intend each function, routine, defined object, and flimberlajammie to do. If you need to change how you go about doing it, but continue to do the same intentions, then the next guy who comes along will be able to see exactly where you’re doing each of the things your program is designed to do, and from there can generally work out how you actually tried to do it quickly and easily.

So. We talked about all this fun stuff, and got pretty enthusiastic about it. And then he said something… well, kind of amazing:

Wes: You know — this one guy I worked with, back at one of my earlier jobs, had a great method. It’s one I still use. See, what he would do is sit down, and write all the comments for his code first.

Me: Huh? How would that work?

Wes: Well, the idea was you were designing your program to do certain things. So by writing out all the comments first, what you’re really doing is planning out just how you intend to execute that plan. You detail your entire program, step by step, function by function, and then you start coding right underneath each section of comments.

Me: So… outlining?

Wes: Yes, but instead of writing a general outline, you’re actually prepping your code section by section. You know exactly where you want to do certain functions and your intentions for how they’ll work. Then, as you actually code, you can just revise the comments if it changes, and that’ll keep the way the rest of the program needs to change at the top of your head. And when you finish — bam, your whole program is commented.

Me: …that’s brilliant.

Wes: Isn’t it?

It is indeed brilliant, because it takes a very useful concept in coding — outlining your program — and transforms it into a list of your intentions for each part of that program. It’s more than a roadmap to your destination — it’s freaking turn-by-turn directions.

[Insert topical Apple Maps sucks donkey joke here.]

And even as we talked, I realized it would work for writing, too.

Outlining is as useful a tool in many kinds of writing as it is in coding, really. Not all writing, of course — there’s a lot of people who write by the seat of their pants, and see where they come out at the end. And that’s fine if it works for them. But others do it because outlining is hard and often artificial. Consider how outlining is done, traditionally. Normally, one of two methods is used: either the writer outlines very specific events in bullet point form….

1. Bob meets the Ninja.

• Bob walks into his apartment. The ninja is there, demanding Bob surrender his cottage cheese.
• Bob and the ninja start fighting!
• Bob’s arm is cut by the ninja.
• Bob kicks the ninja in the junk.
• The ninja cries and surrenders.
• Bob bandages his arm and offers the ninja tea

• Bob and the Ninja sit at the kitchen table, drinking tea.
• Bob asks what the Hell the Ninja’s problem with cottage cheese is.
• The Ninja tells Bob that the dairy the cottage cheese was from is run by the yakuza, and the ninja has sworn to defeat them.
• Bob is skeptical.

…or the writer has a very generic flowchart style outline:

1. Bob meets the ninja and learns about the Yakuza.
2. Karen goes to the mall and fights Yakuza.

Et cetera.

The first style of outline is, for all intents and purposes, a straightjacket. It’s like you’re actually writing the story before you write the story, only minus all that description and dialogue junk. Deviation from the outline can make you throw out everything that follows it, which means you’ll have a ton of work that’ll then get junked — and you have to redo it from that point forward.

The second style of outline, on the other hand, is extremely flexible, and so vague as to be nigh useless. Yeah, it gives you a rough order for the story, but it doesn’t lay out anything that you’re actually trying to do. Honestly, it’s like the first style of outline, seen from ten thousand feet up. You can make out the roughest of events, but can’t actually explain anything about them. If you put the outline in a drawer for six months, there’s every chance you’ll reread it and have no idea exactly what story you wanted to tell in the first place.

Now. Consider the Precommenting Method — where the idea is you convey your intentions for each section instead of the events for each section:

• Bob and the ninja meet. There’s initial conflict over Bob’s choice of dairy products (cottage cheese?), leading to a fight. The fight starts off in a very traditional martial arts story style, and the ninja hurts Bob. However, it’s finished fast by a low blow, breaking the rhythm and subverting the ninja’s tough guy facade. Afterward, they make peace and the Ninja explains the Yakuza’s plot.
• Thematically, both Bob and the Ninja demonstrate the difference between the surface world and the shadow world. 
• Bob’s essential kindness should war with both his OCD and his need for a ‘normal’ existence. He rejects the idea of a shadow culture in the city, and tries to apply Occum’s Razor to everything. The Ninja must be insane, but he’s also upset, so Bob wants to console him. (Offer him tea?) However, even though he rejects everything he’s hearing, he also goes along with it almost immediately — he disbelieves what’s happening, but still jumps in. (Accepts the Surface World, Operates in the Shadow World)
• The Ninja is working from a sense of honor, but it should come across as weirdly fluid — like the Ninja can stretch it to justify any decision, and isn’t really answerable to it. The Ninja wears his identity as more of a mask than his Shinobi Shozoku — he never does give a name beyond Ninja. When the world doesn’t match his idea of what ninjas should be able to do (like Bob’s low blow beating him), he can’t really cope. (Accepts the Shadow World, hides from his Surface World reality) 
• Karen also gets involved — in this case by encountering the Yakuza at the mall….

Et cetera. The idea is to sketch out what each scene is supposed to do in the story, in terms of action, theme, without getting bogged down in the execution. Sure, you throw in a detail or two to convey a sense of your intentions — but those details should be subject to change without notice.

Notice that in the overcomplicated outlining style, there were specifics about the fight and the plot. The Yakuza are definitely doing something with at least cottage cheese, the ninja  cries before surrendering, they drink tea, and so forth. Now, let’s say you actually begin writing the story, and realize two chapters before all this that the whole ‘dairy products’ thing was stupid and too absurd and instead of Yakuza and ninjas, it would work better as Illuminati versus ‘Real Life Superheroes’ style vigilantes. Further, while you’re locked in on events, you have trouble highlighting the thematic dimension. In retooling the story, suddenly a ton of those details are just… well, gone, and either you need to redo the outline completely or largely abandon it. In the ‘comments’ outlining style, you can swap out dairy, Yakuza and Ninja on the fly and still execute the scene (and thematic elements) you intended. In contrast, the overly simplifed version of the outline is… well, kind of useless. You have no idea what you intended either thematically or practically. The ‘comments’ outlining style provides the information you need if you set aside the story and come back to it. In other words, it both explicates your intentions and remains flexible as to your methods.

And naturally, this method can be applied to almost any creative field that follows a sequential path. For a story-based cartoonist, precommenting the work both lets you work out where you want to end up without forcing you into a very rigid progression of strips. For a director, precommenting informs your script and storyboard alike, while making rewrites and mandated changes possible to do without breaking the whole thing. It’s a good thing.

Of course, this won’t work for everyone. Some people work really well with the different forms of outlining, or find a balance between the two extremes. Other people can’t stand any kind of outline, even one as flexible as this. All that’s fine. Some coders can’t stand having more than a vague sense in their head how they want to develop their software, too.

But for the person who wants structure and intention in his writing without being locked down, this is a great way to get there. And for the person who’s done a ton of worldbuilding and doesn’t know how to turn that great setting into an actual story, this method can give you both a sense of actual conflict, theme and progression where before there were none.

Wes and I also discussed memory foam mattresses, but those aren’t as applicable to the creative process.