Author: William

No comment?

I was listening to a podcast recently and one of the hosts made a comment that I’ve heard before. “There are two types of comments – lying and useless.” For the most part, it’s a fair point. When people comment for the sake of commenting, we end up with useless comments – those that simply repeat the obvious. In the following example, the comment doesn’t add to the user’s understanding and in fact makes the code harder to read: DateTime admissionDate = new DateTime(year, month, day); // a date In this case, because the variable is descriptively named, the code is self-documenting; the urge to comment here would suggest that the variable name needs to be updated. Similarly, a comment that describes how a function works is in danger of becoming outdated the next time the function is updated, if the developer doesn’t notice and update the comment as well. This leads to confusion as the comment no longer accurately describes the functionality. In this case, it’s worth looking at whether we can refactor the code to be more clear so that it doesn’t need a comment. What I take issue with is the suggestion that these are the only kinds of comments; I actually find comments to be useful in a variety of situations. Here are some times I use comments: Explaining the whyFor a while, I had...

Read More

Analysis of a Difficult Project

In the eight years that I’ve been a software developer, I’ve had my share of difficult projects. Early on, the difficulty might have been because I was new to development and new to the code base. I had to learn my team’s conventions and how to use our internal tools. Recently, however, I had my most stressful project so far. The initial development seemed to go well enough, but getting the quality to where it needed to be took much, much longer than anticipated. I’m now taking the opportunity to reflect on what went wrong, so I can avoid making the same mistakes in the future. Project Summary In this project, I was taking some legacy code and rewriting it to be web-based. I’ve probably done this ten times before, but this was one of our most complicated activities. It was also one of my first projects since we switched to a quarterly release cycle, which meant more pressure from deadlines. I won’t go into more detail than that, except to say that due to the nature of my job, the quality of released code has to be very, very high. The possibility of a data integrity error – either from a programming mistake or because the user is confused – is simply not acceptable. Design Part of our process is to have a design for each new piece...

Read More

Instant Family

Last week I finally got around to seeing Instant Family. If you’re not familiar with the movie, it follows a childless couple who decide to adopt out of foster care. As expected, crazy hijinks ensue. I have to say that I enjoyed the movie quite a bit. It has a lot of humor, while still (pretty) accurately representing what it’s like to be a foster parent. One thing to be aware of is that this movie is definitely from the foster parent perspective; it’s about how the foster parents fight through the process and (of course) come to learn that their kids are what was missing from their lives. If it was written from the foster child perspective it would be a very different (and probably much less funny) movie. From the perspective of the parents, their lives are being turned upside down because they now have three kids with behaviors that they aren’t prepared for and can’t control. From the perspective of the kids, their lives are turned upside down because they’ve been moved to a new home and don’t know what’s going to happen to them; almost everything in their lives is outside of their control. I don’t know if I would show this movie to (especially younger) foster kids – as I said, it’s not aimed at them and could be upsetting – but for people...

Read More

On Writing

I’ve been working on a technical book for several years now. Partially, this is because I have a million things to do (coincidentally, my son just turned two). Partially this is because I’m a slow writer. And partially…it’s because writing is hard! Here are a few things to improve the process: Don’t write technical material in Word. Seriously, just don’t. Fortunately I learned this one many years ago – I used to type up my homework for my Algorithms class (due to my lousy handwriting) and it didn’t want long to determine that the effort to figure out LaTeX was less than the effort to get mathy things to work correctly in Word. Once you’ve written something, leave it along for a while and then print it out to proofread it. It’s amazing how many typos you can find once you’re looking at something in a different format and state of mind and can read what you wrote rather than what you meant to write. If at all possible, have somebody else read your work. Sentences that make complete sense to you might not work for someone else. If possible, get a reader who belongs to your target audience and can confirm that you’re not assuming background knowledge or ability that your readers won’t have. Don’t assume you know what your readers want. In my case, I was expecting...

Read More

Doing big things

Fans of Marvel movies know to wait around until the end of the credits to see the extra scene. This adds a bit of time to the theater experience, as the credits go on for quite some time; it takes hundreds of people to make a movie on that scale. At work, I’m one of a dozen developers on my team and one of several thousand developers in the company. While each team largely sets its own policies, there are some general standards for consistency across the company. Even relatively small side projects tend to involve several people. I’m currently finishing a small computer science textbook that I’ve been working on for the last few years. Even though I have a PhD, work experience in both writing and editing, and a tendency to do everything myself, my book still has a technical editor, a copy editor, and a graphic designer. I could certainly finish the book without any of those people, but they’ll help me to make it as good as it can be. In short, any project of significant complexity, even if it’s small enough to be done by one person, will benefit from having multiple sets of eyes. When multiple people are working on the same content, however, it’s important to have standards for consistency and for resolving disagreements. Sometimes this means there’s one person in charge...

Read More