Monthly Archives: September 2008

All Good Writing is Rewriting

While I was at Grinnell, I wrote a lot of papers. More than 70 by my count. Over time I learned to embrace the maxim that “all good writing is rewriting.”

Now, as a software engineer I write proposals, technical specifications, documentation and (of course) e-mails. All of these require writing, editing, proofreading and rewriting. This shouldn’t surprise anyone.

What you may find surprising is this: Writing software follows the same pattern. Write, edit, proofread and rewrite. No matter what the creative endeavor, no one should expect to get the final product on the first pass. And writing software is a fundamentally creative activity. Usually, it takes several revisions to get “good code.” (The exact number depends on the target audience and how much you want to impress them.)

When writing software — as opposed to prose — I tend to look at the following things when editing my own code:

  • Are the statements/commands in the most logical order for reading the code?
  • Can I hide distracting details in another procedure, module or datatype?
  • Can I be more terse without obfuscating the code’s meaning?
  • Are there more advanced language features I can use to hide complexity?
  • How can I change this routine to make it the “right size?”
  • What assumptions do I need to make explicit?
  • What exceptional situations have I not handled?
  • How can I improve the names of variables and functions within the module?

I find that editing code works best when I treat it as if I were editing prose. That is, I print it out, get out a red pen and mark the copy. I need to be able to make notes, strike things out, bunch things together and jot the outline of code I want to add. I don’t want to get bogged down actually making the changes while I’m being critical, yet when I’m done I have something like a checklist that I can use while rewriting.

Here’s an example of some recent rewriting of a feature that’s probably going into MATLAB sometime in the next six months. Because we haven’t shipped it to customers, I feel compelled to fuzz out parts that might let you figure out exactly what it does. But hopefully there’s enough detail there for you to see the evolution of the code.

It’s also worth noting that the underlying functional design hardly changed between the first and last versions. The changes were meant to clarify the design and facilitate maintenance and enhancements. But it’s not true refactoring, since I did change some of the functionality between project iterations. (That almost always happened independently of rewriting, though. Rewrites should be behavior preserving. Then add new features, submit to source control and edit/rewrite.)

The first two scans below show the first and fourth revisions of the file; they’re pretty heavily marked. The last scan is the current/final version. Click any image for a more readable version.




Version 1: 9/16/2008




Version 4: 9/19/2008




Version 5 (Final): 9/22/2008


Posted in Software Engineering | Leave a comment

Announcing a Series on Design Patterns

The first week of my final semester of grad school is in the bag. This go-round is all about software design, both low-level (“RSEG 109: Object-Oriented Design“) and high-level (“RSEG 290: Special Topics: Design Patterns”). When you add in the reading group we’re starting at work, this could also be called the “UML semester.”

Design patterns give a shared vocabulary for talking about common software design features, present how and when to use a design, and lay out the trade-offs of using a particular design. They aren’t as widely used as they should be in a profession that claims to value reuse. I think that’s a shame.

As part of the design patterns course, I must create an object model for a real-world problem. And along the way, I’ll be learning about most of the two-dozen OO design patterns in the Gang Of Four book. (Usually I don’t present solutions to my homework in public because I feel it could help the next semesters’ students cheat; but this semester we’re each doing our own thing.)

Since I’m learning about them, I’ll do my best to write about them over the coming weeks. If all goes well, I’ll have an outlet to reinforce what I’m learning; and you, my dear readers, will have a gentle on-ramp to design patterns, too.

Here’s the description I submitted last night of the software system I will design:

I will apply design patterns to a simplified web content management system, colloquially known as a “blog.”

While blogs frequently are vehicles for cute kitty photos, angst-filled teen poetry, and ill-informed political shouting, this CMS will not know anything special about its content. Here’s what users will be able to do with it:

  • The blog author(s) will be able to write new articles and edit them before publishing.
  • Authors will be able to preview articles before publishing.
  • Authors will be able to post articles and have them appear on the web.
  • Authors will be able to edit articles after they are published.
  • The blog’s readers — supposing there are any — will be able to post comments in response to articles.
  • The CMS software will display the following elements: static text, linked images, embedded objects, and dynamically generated content.
  • Authors can activate/deactivate “plugins” that implement a well-defined API.
  • Authors will be able to change the appearance of the blog by selecting from an arbitrary set of “themes.”
  • Readers will be able to display single articles or an archive of articles showing a full month of articles.
  • Readers can navigate from one article (or set of articles) to the prior or next article (or set of articles).
  • The author can choose whether the CMS stores articles in a database or in a flat-text file.

So keep tuning in, and we’ll take a tour through design patterns for object-oriented software reuse. And please post comments about where you’ve been able to use design patterns successfully, if you see anything you would have done differently, or if you just want to leave your two cents.

Posted in Computing, From the Yellow Notepad, Software Engineering | Leave a comment

Article on High Dynamic Range Imaging and MATLAB

Peter Webb, one of my coworkers, published an article entitled “Rendering High Dynamic Range Images on the Web” in the July 2008 issue of the MATLAB Digest. Enjoy!

Posted in Color and Vision, Fodder for Techno-weenies, MATLAB, Photography | Leave a comment

Photography Podcasts

I am a serious podcast junkie. I currently have over 16 days of unheard podcasts. News, arts and culture take up most of my bandwidth.

Recently — and by that I mean the last few months — I’ve been working on two big podcast series.

Earlier in the summer I finished listening to Jeff Curto’s excellent History of Photography Podcast. As someone who liked school, loves photography and dabbles in history, I found myself really getting into the fifteen-part rebroadcasts of Curto’s college course.

I can hear some of you out there now. “But, Jeff, it’s an audio podcast. And photography is an inherently visual medium. How does that work?”

Well, the podcast has two things going for it. First, the podcast is enhanced with a lot of photographs, which are in sync with the lecture. Furthermore, Prof. Curto is a very gifted lecturer. He describes the photographs quite well, along with the ideas they contain and the artists who made them. (It probably helps that I had previously seen many of the photographs, too.)

A new semester of classes just started, so consider subscribing to it.

I also want to mention Adobe’s Lightroom podcast.

I love Lightroom! It’s a brilliant piece of software for photographers, taking all of the most important parts of Adobe Photoshop that a photographer needs, adding superb image management features, and putting it within a user interface that emphasizes workflow. It challenges the widely held view among geeks (and probably most software users) that powerful software has to be difficult to use. It makes me want to write better software myself.

So what’s so great about a podcast about Lightroom? George Jardine, formerly the product manager of Lightroom, brought together a diverse group of people during the public betas of Lightroom and had them talk about a bunch of subjects that really interest me. Professional photographers discussed photography and their digital workflows, which gave me ideas how to improve my own. A couple of analog printmakers took the long view, helping me think about how to make better digital prints. And then there were the software engineers.

Software engineers? Really?

Yeah, it sounds odd, especially since I try to keep my photography discussions about art and not about gear or f/stops or color profiles or pixels. But . . . I know a few things about image processing, color science, and software engineering. And I know how hard it is to make really great software. So I really appreciated being able to learn tidbits from people with more experience than me, as they talked about the things that interest me. And these guys aren’t just dilettantes. No, these Adobe engineers are deep into it; they know the trade-offs you have to make in the real world when implementing image processing and I/O algorithms. And did I mention that they worked really, really hard with Lightroom to get it right.

If you use Lightroom and want to get some ideas how to use it more effectively, you should listen to the podcast. Or if you just want to hear about the evolution of a software project, it’s also for you.

Finally, check out Edward Burtynsky’s SALT lecture on the “10,000 Year Gallery”. The SALT (Seminars about Long Term Thinking) podcasts by the Long Now Foundation cover a wide range of subjects, all of which attempt to get us to think on a millennium-long timeframe. (At first I thought it was something like a cult or a Burning Man-esque art project; but now I see it for what it is: transcendent, if somewhat eccentric.) Anyway, Burtynsky is helping create a gallery of photographs about who we are today that should last at least 10,000 years and will be installed inside an enormous clock that will toll every 10,000 years. Seriously… Not the most exciting podcast episode, but in general the whole seminar series is worth listening to.

Posted in Computing, Fodder for Techno-weenies, History, Photography, Software Engineering, This is who we are, Worthy Feeds | 1 Comment

Quickly Finding Numeric Patterns in MATLAB

Comrade programmers!

About five years ago I wrote a little program to help me find numeric patterns in arrays. Basically I needed to find byte patterns like 0xFFFE 0xE000 in the data from DICOM files. Something like MATLAB’s strfind function, except more general than looking for substrings in strings.

So I wrote a rather naïve algorithm to do just that. It wasn’t very fast, but it worked for exploratory use. But then today I needed to do something like that in production code. So I asked one of my coworkers for tips with a faster implementation.

Turns out the strfind works just as well on numeric arrays as it does on strings. And it’s really fast, too.

% "data" is a 1,200,000 element UINT8 array. % It contains 29 instances of the pattern. tic; offsetTable = strfind(data, [254 255 0 224]); toc % Elapsed time is 0.027390 seconds.

Update: Loren Shure posted an even better solution on her blog.

Posted in Computing, MATLAB | 2 Comments