A Pair of Coding Aphorisms

I write software for a living, and I take great pleasure when fixing a problem means reducing the number of lines of code in the system. In the last two days, I have come up with a couple of observations:

Every line of code is a pre-cancerous cell in the body of your application.

Now, “line of code” can be a deceptive measurement, as cramming a whole bunch of logic into a single line will certainly not make the application more robust. There are even robots that can comb through your code and sniff out overly-complex bits. But just as in humans weight is a proxy for a host of more meaningful health measurements, lines of code is the proxy for a host of complexity measurements.

But the point stands. I recently had to fix a bug where someone had copy/pasted code from one place to another. Then the original was modified, but not the copy. All those apparently-safe lines of code (already tested and everything!) were a liability, where instead a function call so everyone used the same code would have been more compact, easier to read, and much easier to maintain. There’s even an acronym for this type of practice: DRY — Don’t Repeat Yourself.

While that’s one of the more flagrant ways code bloat happens, there are plenty of others, mostly symptoms of not thinking the problem through carefully at the get-go, or not stopping to reconsider an approach as the problem is better-understood. Stopping and thinking will almost always get the project done sooner — and smaller.

One important thing to keep in mind is that programming languages are for the benefit of humans, not the machines that will eventually execute the program. If the purpose of your code is not obvious from reading it, go back and do it again. Comments explaining the code are generally an indication that the code itself is poorly written.

No software is so well-written that it ages gracefully.

I work on a lot of old code written by others, and I know people who work on old code written by me. In some cases, the code was shit to start with, but in others time has simply moved on, requirements have changed, and the code has been fiddled and futzed until the pristine original is lost to a host of semi-documented tweaks.

Naturally no code I have ever written falls into the “shit to start with” category (how could you even think that?), but that doesn’t mean the people who have to maintain that old stuff won’t be cursing my name now and then, as some clever optimization I did back in the day now completely breaks with a new requirement I didn’t have to deal with at the time.

And sometimes even if the code itself is still just fine, the platform it runs on will change, and break stuff. Jer’s Novel Writer was pretty elegant back in the day, but now when I compile I get literally hundreds of warnings about “That’s not how we do things anymore.” Some parts of JersNW are simply broken now. When I no longer work where I do, I will likely rebuild the whole thing from scratch.

Speaking of work, I am very fortunate to work in an environment that allows us to trash applications and rebuild them from scratch every now and then. Having a tiny user base helps in this regard. And as we build the new apps, we can apply what we’ve learned and maybe the next system will age a little better than the one before. Maybe. But sure as the sun rises at the end of a long day of coding, someone will be cursing the new system before too long.


22 Rules of Storytelling According to Emma Coates

Emma Coates is a storyboard artist for Pixar. This is a list of storytelling rules and tips she has shared with the world via Twitter. Some of them may seem pretty obvious, but when you take the list as a whole, chances are you’re going to find ways to make your current creative project better.

Here we go!

#1: You admire a character for trying more than for their successes.

#2: You gotta keep in mind what’s interesting to you as an audience, not what’s fun to do as a writer. They can be v. different.

#3: Trying for theme is important, but you won’t see what the story is actually about til you’re at the end of it. Now rewrite.

#4: Once upon a time there was ___. Every day, ___. One day ___. Because of that, ___. Because of that, ___. Until finally ___.

#5: Simplify. Focus. Combine characters. Hop over detours. You’ll feel like you’re losing valuable stuff but it sets you free.

#6: What is your character good at, comfortable with? Throw the polar opposite at them. Challenge them. How do they deal?

#7: Come up with your ending before you figure out your middle. Seriously. Endings are hard, get yours working up front.

#8: Finish your story, let go even if it’s not perfect. In an ideal world you have both, but move on. Do better next time.

#9: When you’re stuck, make a list of what WOULDN’T happen next. Lots of times the material to get you unstuck will show up.

#10: Pull apart the stories you like. What you like in them is a part of you; you’ve got to recognize it before you can use it.

#11: Putting it on paper lets you start fixing it. If it stays in your head, a perfect idea, you’ll never share it with anyone.

#12: Discount the 1st thing that comes to mind. And the 2nd, 3rd, 4th, 5th – get the obvious out of the way. Surprise yourself.

#13: Give your characters opinions. Passive/malleable might seem likable to you as you write, but it’s poison to the audience.

#14: Why must you tell THIS story? What’s the belief burning within you that your story feeds off of? That’s the heart of it.

#15: If you were your character, in this situation, how would you feel? Honesty lends credibility to unbelievable situations.

#16: What are the stakes? Give us reason to root for the character. What happens if they don’t succeed? Stack the odds against.

#17: No work is ever wasted. If it’s not working, let go and move on – it’ll come back around to be useful later.

#18: You have to know yourself: the difference between doing your best & fussing. Story is testing, not refining.

#19: Coincidences to get characters into trouble are great; coincidences to get them out of it are cheating.

#20: Exercise: take the building blocks of a movie you dislike. How d’you rearrange them into what you DO like?

#21: You gotta identify with your situation/characters, can’t just write ‘cool’. What would make YOU act that way?

#22: What’s the essence of your story? Most economical telling of it? If you know that, you can build out from there.

I think the one that I have to watch for more than any other (that’s not to diminish any of them) is #18. I can fuss over a stretch of prose indefinitely. One of the reasons I created Jer’s Novel Writer was to easily mark places where I felt the need to fuss, so I could fuss over them later, and get on with writing. The confidence that I can fuss later allows me to move on.

I also like #9, about making a list of what would not happen next.

I came across this list via a commercial email that credited io9 for collecting the tweets. io9 doesn’t credit anyone else for doing it, so we’ll give them a hearty thumbs-up for the actual labor required to make this list happen.


Jer’s Novel Writer 1.1.10 Released!

It’s a big milestone for me, getting back on track maintaining Jer’s Novel Writer. For those of you who are not familiar with it, JersNW is a word processor with features to help my scattered thoughts fall into some sort of coherent form. It’s based on three principles:

  1. When I get an idea, I want to be able to jot it down without losing my train of thought.
  2. I don’t want to have to remember stuff, and when I need to find something I wrote before I can look it up without getting caught up in the part of the story where it happened.
  3. When I’m stuck on a line or know it could be better, or need to check a fact, or need to track continuity, I can flag it and know I’ll be able to get back to it later.

There are features to help with the mechanics of writing as well (drag-and-drop chapters, flexible database, and so forth), but mainly I just want to keep my momentum when the creative juices are flowing and know that when nitty-gritty time comes I’ll find the places that need attention. Man that’s liberating.

If you’re interested, you can learn more at Jer’s Software Hut. Enjoy!

Oh yeah, it’s Mac-only.


Jer’s Software Hut Returns!

Deep below the Earth’s surface, in a steaming chamber somewhere between the Hayward and San Andreas faults, there is motion in the dancing shadows cast by the guttering torchlight. Dark, twisted creatures stir. They move slowly, their once-lean haunches soft from months of torpor. They shamble from their stony sleeping-nooks into the work chamber, and one by one they take their accustomed positions on the capstans. The great wheels resist at first, then start to turn with a shriek that slowly fades to a rumble.

From the throats of the horde comes a deep ululation punctuated by coarse barks, a sound that reverberates through the chamber until it has no source, merely presence. It is enough to weaken the knees of even the stoutest hero, a sound to chill the most stalwart heart.

The creatures are singing.

Though fearsome in sound, it is joy they express; the sublime joy of one who had no purpose being useful again. Far above them, in a peaceful neighborhood San Jose, those turning capstans once more power the forges and shrieking spark-throwing wheels of Jer’s Software Hut.

On the slab in the middle of the laboratory a figure stirs; what once was dead now breathes again.


Jer’s Software Hut Falls Silent

The shadowy, misshapen minions have all gone home; the vast underground chamber that once rang with their chants as they turned the giant wooden capstans has fallen silent. The river of lava flows unimpeded, the precarious rope bridges spanning it falling into disrepair. Above, the streets of Sky City Research Facility, once teeming with antigravity cars, are empty, the crystalline architecture acquiring a layer of eagle guano and dust that is transformed into gritty runoff when it rains.

The crudely-crafted Web site at jerssoftwarehut.com no longer accepts payment for Jer’s Novel Writer software licenses, and bears the following statement:

Well, it’s happened; I have a regular job. As I slave away working for the man I often wonder if things might have been different had I only worked harder at making Jer’s Software Hut a business rather than a hobby. Probably now we will never know. It was a good run but it’s time to ackowledge that development is stalled and customer service around here has been really awful.

That pretty much says it all; despite thousands of happy users, some of whom even paid for the software, when it came time to have a steady income again I took the safer path of working for someone else. (The ironic twist to this narrative I will leave for another time.)

It was a good run, and as I get my work life under control I hope soon to at least return to using Jer’s Novel Writer for its intended purpose – as a writing tool that helps me create fiction. Until I do that I can’t even consider opening the shutters on the Hut and throwing the big switch that raises the lightning rod into the violent midnight thunderstorm, while sparks fly and the turbines spin faster and faster, the needles on their gauges creeping ominously into the red. Maybe someday, though. Maybe someday.


World Fantasy Convention!

Well, it’s official; I’ve paid my money and everything. I’m going to this year’s World Fantasy convention, and I’m not at all sure how to prepare. It’s the sort of event I should have been attending for years now, and being able to do stuff like this is a fortunate side-effect of living in North America.

On that subject, aren’t these things supposed to have wacky names that end in ‘con’?

So what is this convention? As far as I can tell, it’s an event where boatloads of writers and publishers and agents and other industry folk gather for three days of… stuff. Elbow-rubbing. Looking for deals. Writers trying to get published, publishers trying to find writers that don’t suck. Panel discussions and whatnot. A few key people who are paid to come and encourage the masses. Others who have come simply for the love of the genre.

If all that sounds pretty vague, it’s because I’ve never been part of one of these things before. It’s an important part of my chosen profession, however, and contacts I make at this thing could turn my career. Or not. Or maybe I’ll make an impression with someone that pays off years from now. You never know.

I do know it pays to be prepared. To have things to hand to publishers and agents that they will love, things that at a glance will tell them that they are just dying to read my novel. “Stop the presses!” they will shout into mobile phones, “we have to rearrange the 2010 catalog!”

Another opportunity I have is to impress people in person in ways that anonymous submissions never can. I can talk to important people and leave them thinking “That guy’s an intelligent, articulate guy with a refreshing vision of the fantasy novel.” This will simultaneously be the easiest and most difficult thing for me to do. Once I get into a conversation with the right people, I’m sure I’ll do well. (I’ve been lying awake at night devising my elevator pitch.) The thing is, I’m really, really bad at getting into those conversations in the first place. I’ve been to other industry conventions and utterly bombed at networking (even at the conference about networks).

So, anyone out there have any suggestions? Both for specifics that I should take with me and for the more general hob-bobbing? Any help will be greatly appreciated!

Getting the Hut Back Up and Rolling

Um… actually two releases. The first didn’t last long.

It’s been a while since I’ve really knuckled down and worked on Jer’s Novel Writer, but after wrestling with the script to extract data from iBlog to export to WordPress, my brain has been sliding into technomode, and it was nice to work in a programming environment that was less frustrating than AppleScript. I had a version of Jer’s Novel Writer that I’d done some work on a while back, but it took a while to get myself back up to speed on just what was going on in the code.

I missed something on my first try. Happily a loyal user caught it almost right away, and one day later version 1.1.8 is out there, helping people write. Whew! Slowly things are returning to the balance I’d managed to keep for the last few years. The last few months have been… less balanced. (Obviously I’m operating in the geek hemisphere right now. No metaphors for you today!)

Meanwhile, a few days ago I got this!



Thoughts while Sitting at My Desk

I am sitting in our office right now — I am at my desk and That Girl is behind me, working on a project of her own. This is a very satisfying way to be, for a wide variety of reasons.

First, of course, is the very presence here of a place called ‘my desk’, to be found in ‘our office’ in a home that also contains That Girl. The second satisfying thing is the presence of That Girl’s desk in the same office. Third, there is the fact that we are both able to be productive in this arrangement. (Your definition of ‘productive’ might not match mine — for instance I consider writing this blog to be productive.) So that’s all good.

It’s critical that we can get things done in this arrangement, as That Girl was laid off while I was out stomping around in Kansas. If you don’t count the whole “no money, no security” part of the equation, it’s working out pretty well. That Girl has been ramping up her online poetical presence, working to market herself and maybe even get to where she can support herself doing what she loves most.

I’m hoping to get to that place as well, of course. I’ve been spending the last week working on Jer’s Novel Writer. A recent operating system update made a few pieces work oddly. (Yes, that is a euphemism for ‘wrong’.) While I had the hood up I wanted to fix a couple of other issues. The software is nearly ready for release, better than ever, but that hasn’t left a lot of space in my brain for using the software for its intended purpose, which happens also to be my intended purpose.

Once I get this release out, I will be turning back to my writing (and, ideally, blogging). I have a whole bunch of things to work on. At the start of the week I thought, “I’ll get that bug fixed and then get one thing ready for submission per day for the rest of the week. Here it is Friday and there’s not much rest of the week left.

If I sigh really heavily, sometimes That Girl rolls across the office and gives me a hug.

Exchange Rate Blues

I charge $30 for a license that allows a person to use Jer’s Novel Writer without being nagged occasionally. When I first came to visit the Czech Republic, that money could buy me more than 120 beers at one of the cheaper places. Now, just a few years later, thirty bucks buys about 22 beers in the same bars.

Bit by a Leopard

I hadn’t really been paying attention to the hype (if there was any), so the release of Apple’s OS X 10.6 “Leopard” (someone in the marketing department over there needs a good talking-to) caught me by surprise. I hadn’t preordered it and I first learned it was out when reading a Web comic. The second place I heard about Leopard was from a user of Jer’s Novel Writer. That message: “it’s broken!”

Grand. Over the weekend I searched Prague for a store with Leopard in stock. Nope. No clue when it might arrive, either. There was a hint of bitterness on the part of some shopkeepers, a small resentment at being second-class citizens in the eyes of Apple, but mostly just the Czech shrug. Wait and see.

“It’s an emergency,” I explained to one clerk. “Can you find out when it might come in?” She answered in the negative. That doesn’t mean it was not possible to find out, it meant that she wasn’t going to try. (“It’s not possible” here means “I don’t know how and I can’t be bothered to figure it out.”)

I’ve gotten some helpful diagnostic information back from a couple of users, and I’ve built a shot-in-the-dark attempt at a fix. We’ll see how it goes. Meanwhile, I’ll be turning to mail order today. Why couldn’t Apple have delayed just a little longer, until I was in the U.S.?

ADDENDUM: HEY! APPLE! Czech Republic is a country too! It’s in Europe and everything! First I wasn’t eligible for your software contest, and now you won’t even ship me your product! AAAAAAAARRRRRRGGGGGGHHHHHHHH!

I feel better now.


A Milestone, of sorts…

Well, it’s official, Jer’s Software Hut is a multi-product company. Someone went to the trouble to slide me five bucks for Jer’s Flash Card Viewer.

As I prepared the key file it occurred to me that the whole key system in the viewer hasn’t really been tested that much. In fact, I couldn’t quite remember how it was supposed to work. Had I made it so that double-clicking the key would work, or was it using the old drag-to-the-folder method? I played it safe with the instructions, generated the key, and sent it off.

Thus opens a grand new revenue stream for the Hut. With the dollar continuing to tank it is only worth about three or four beers, but that should cover my bar tab tonight when I go to hear a friend do some sort of musical act.

If I was smart, I’d use my connections in the textbook industry and get one of them to include JersFCV as a supplement to a language textbook. The downside is that it would cost me a chunk of cash and time to even start working on a Windows version. Whoever paid me would have to foot the development cost.

In fact, after writing the above I composed an email to my former boss in the Educational Software Biz. If he wants to sell Jer’s Flash Card Viewer to his clients, I’m sure not going to stop him.

Odds and Ends

I should mention that I have the cover story over at Piker Press this week. It’s set in the Tin-Caniverse, a neighborhood of the Science Fiction multiverse in which a few laws of physics have been suspended for being inconvenient. It’s the first in the series told in the third person, and the continuity issues between this and the previous installments I chalk up to conflicting memories. We won’t consider that one person is remembering something before the other person experiences it. In fact, in this case we can temporarily reinstate relativity to make traveling faster than light a form of time travel, explain away the problem, and then put that pesky law of nature back in the drawer.

I’m pretty happy with the story, but reading it now that it’s been published, I think I left a little on the table. No such worries about my story that will be published over there during zombie month. Zombie Month! Where have you been all my life? I’ll let you know when my modest submission is up; it’ll be a few weeks, yet.

I’ve settled on my NaNoWriMo story, but I really don’t know what I’m going to do with the idea. It’s a comedy based on the statement “When math is outlawed, only outlaws will do math.” In a world where governments willfully keep the populace ignorant, what would a revolutionary look like? It’s got lots of possibilities. I picture street gangs that hang out in ‘math houses’, leaving elegant mathematical clues how to find them scrawled on walls throughout the city. I think I’ll start with a scene where during a police raid the protagonists must convince the cops they were only doing drugs, and that the drugs were obtained through sanctioned sources.

This morning I put out a new release of Jer’s Novel Writer. The last version had a bug that only happened to users installing the software for the first time. Not good, and of course none of my usual testers were going to catch something like that. I’m not exactly sure how long the bad code was in there, but the problem manifested most obviously in the last release. I wonder how many odd problems people have been having over the past months were caused by the bug. Ai, ai, ai.

On Monday What’s-Her-Name sent me a message asking if I was free. I haven’t seen her since her brief tenure as a bartender at Little Café Near Home. My phone and I don’t really get along, though, and I didn’t see the message until about an hour ago – three days late. Somewhere, the capricious gods of telecommunications are laughing.

Finally, do any of you remember reading an episode about the Awkward Bowling League? I wrote it a couple of weeks ago, and now it’s… gone. There’s no sign of it. I was going to write a follow-up, and I wanted to read the original first and link to it. I’m just wondering if it vanished before or after you guys got a chance to read it.

[Late Addition!] Five cover letters tonight. I just have to assemble the parts, and I’m caught up. Got a smiley-face infested message from What’s-her-Name, so that’s cool. Getaway Cruiser is playing some good noise into my head right now. Things could be worse.


A Competitive Analysis

Final Draft is to writing screenplays what Microsoft Office is to business communications. They have quite a bit in common, those two programs; not in their features per se but that their features go far beyond just putting words to screen. In fact, Final Draft is really bad for putting words to screen.

In fairness, there are some features that really speed up the process of writing a screenplay. There are keyboard shortcuts to easily format things in the industry-standard way, and typeahead for names and previously-used scene names. Because it formats the document as you go, it knows when you are typing a character name or a scene intro, so it is able to help you along. Once you get used to that part, you can save a lot of keystrokes.

But holy crap what a dog of a text editor. To start with, it’s ugly. You have to go out of your way to make text that ugly on a Mac, and they have. The thing is fraught with display problems, and often a click on one line will yield a blinking cursor somewhere else. Then there are the times the screen is completely whacked out.

There are no excuses from the Final Draft boys on this; Jers Novel Writer also has discrete sections with predefined styling for each type of section, and it has none of those problems. It was written by a guy in a bathrobe. Of course, much of the problem with Final Draft is likely because they want to use as much of the same code as possible in the Windows and Mac versions, meaning they can’t really leverage the almost-magical text-rendering features on the Mac, and I suspect they also can’t use the best of Windows either.

[NOTE TO STEVE JOBS: Cocoa for Windows! Come on! You don’t think the Final Draft people wouldn’t be all over that in a heartbeat? Hell, they’d probably license my code. Imagine this pitch. Geek: “We want to use Cocoa.” Suit: “Why?” Geek: “It’s an amazingly innovative framework that will reduce development time and run wicked fast both on Macs and Windows with no extra effort on our part.” Got that Steve? Cocoa for Windows. It’s your Next Step toward world domination. (Insider pun accidental but embraced.)]

Of course, Final Draft has no margin notes and no database. Jer’s Novel Writer doesn’t have a notecard view of all the scenes that you can flip through and rearrange (a feature I can appreciate though I have yet to use). The closest thing to that is the automatic outline in JersNW, which I really, really, miss when working in Final Draft. fuego has pointed out in the past that the notes features of JNW would be really useful during production as well.

Final Draft is, I think, a well-named product. It has all kinds of stuff to help during production (things like pink pages – insertions and removals don’t affect surrounding page numbering, so all the people who have information that refers to a script page don’t have to go back and update everything when a scene is deleted. You can print out the page changes (each time you do you use a new color, thus ‘pink pages’), and people can update. A meeting can start with, “OK, everyone have the ochre pages?” and you know that everyone’s up to date. There’s no way I’m putting that into Jer’s Novel Writer.) That’s all cool. Final Draft is a very useful program once you have the final draft.

Another thing that Final Draft is very good at, something that almost redeems it, is that when you paste in text that is formatted with some reasonable level of consistency, the program is quite remarkably good at interpreting the text and formatting it. Hopefully the guy who wrote that code has a BMW to go with his ulcer. Now I’m working on Dark War, using Jer’s Novel Writer, laboriously typing out people’s names every time and making sure the right parts are all caps. Still far better than writing a first draft in Final Draft. At some point, when I have to share the work, I’ll past the whole mo-fo into Final Draft.

Maybe the Final Draft guys will someday remember that they are selling software for writing a screenplay, not just managing one. Maybe it’s time for Jer’s Screenplay Writer.

Rakin’ in the Big Bucks!

Now that Jer’s Novel Writer is selling just a little more briskly than I had hoped, which sure is nice (my warm gratitude to all those folks who have purchased a key… you guys rock!), I can breathe a little easier about the whole eating-and-paying-rent thing. It will be longer before the money runs out.

Nice mug!

You want one. You know you do.

And now, today, a whole new revenue stream opened up! Yowza! Yes, the laws of statistics dictated that sooner or later it would happen. With billions of people bouncing around on the Internet, and some percentage of those people either intoxicated or otherwise mentally challenged, it was only a matter of time before factors converged and someone clicked the fateful button.

Someone bought a Suicide Squirrel Alert Coffee Mug.

I’m not sure how long I’ve had the link over there in the sidebar, but it’s easily been more than two years. Piker Press will put a link to Jer’s Junk up when I have something in the current issue (thanks guys!) so it’s quite possible that this sale was related to my Peek of the Week over there this week.

Yep, 2 1/2 years, one mug sold. It doesn’t sound terribly impressive, but when you consider it in terms of percentage growth, this year has been explosive! And don’t worry, you can still be the first on your planet to sport a Suicide Squirrel t-shirt!

SSDC t-shirt

I think I’ll spend some time today on the Muddled University merchandise.

Finally, thanks to those folks who start their Amazon shopping adventure by clicking the link over there in the sidebar.

One Point Friggin’ Zero!

I was in the Secret Labs this morning, floating aimlessly through the glossy, high-tech warren of tunnels and chambers drilled through the rock and metal of Asteroid 2029 as it orbits the distant sun here in this quiet Prague neighborhood, when I made the decision.

“Ship it,” I said to myself, and Jer’s Novel Writer 1.0 was released to the world.

I’ve been working on this thing for a few years, now. One of the reasons it took so long to get to 1.0 is because along the way the growing body of users has been full of ideas, suggestions, and constructive criticism. Some of my favorite features were things I would never have thought of on my own. The long gestation period means that 1.0 is way, way cooler than I imagined it would be when I started out.

Still, it’s about stinkin’ time. One thing that makes version 1.0 different than just another incrementally better beta release is that this one is technically not free. Users have been able to pay voluntarily for a while, and it’s really cool when I get the “You’ve been paid!” message. It will be interesting to see if people’s behavior changes as all. I estimate that I have already earned more than ten cents per hour for coding this thing  (if you don’t count classes, hardware, or any other expenses — let’s not think about that).

It would be sweet to sell enough copies to live off the proceeds, but that seems unlikely, even living here. Maybe if I move to Ukraine…

You know what would be even sweeter? Some day I want to be sitting somewhere in the world, writing my next best-seller when someone looks over my shoulder and says, “Hey, Jer’s Novel Writer! I use that too!” That would be almost as cool as happening upon someone reading a book I wrote.

That’s all the future, however. Today is about hitting a milestone, a big event that could affect my life. Today is 1.0 day. (It’s also Over-Easy Day. Dang, already a doubled-up day. What are the odds?)