The karma of bad software documentation

Tried to use someone’s software library.
Documentation was bad, couldn’t get it to work.
Used someone else’s.


MacOS softwareupdate command (how to ignore updates)

I just learned that MacOS has a softwareupdate command, and further learned that it has a --ignore option, which may or may not let you ignore useless updates. For example, my Mac prompts me daily to update Keynote, Numbers, and Pages, which I rarely (rarely!) use, so I don’t want to bother updating them. I’m hoping the a softwareupdate command will help me with this.

Software best practice: Never say “X% done”

Note: This is a post from 2007 that I just updated a little bit because I think there’s still some value in it.

A lot of people have written to say that it’s unfair that I think developers should never say “I’m 75% done,” or “I’m 90% done.”

So, to explain myself, here’s why I think you should never use a phrase like that:

Balancing development desire with product goals

This article about balancing quality and product features (from the perspective of a CTO/CIO) is a good read. The editor’s note states, “This is part of a series exploring the trials and tribulations of first-time managers. Camille Fournier, former CTO at Rent the Runway, is often asked for advice on how to make the transition from an individual contributor to a manager.”

Software bugs help doom Japanese black hole satellite

In another example of a high-profile software quality problem, Gizmodo reports that a Japanese satellite that was meant to observe black holes was doomed by poor software quality:

“It was only up there a month when something went wrong. A series of unfortunate events caused by both human errors and software flaws sent the satellite spinning out of control.”

2015 Subaru Outback: Poor software quality

I have a 2015 Subaru Outback, and while the basic “car” is good, the software in the car is often comical, as in comically-bad, including bugs and poor design decisions. This image shows that my car has gotten 76.2 MPG over its lifetime, which is off by about 50 MPG.

It may be that this piece of data is trying to convey something else, so in that case it would just be poor design and not wrong data, I don’t know. But I shouldn’t have to dig through the car’s manual while driving 75 MPH on I-70 to figure out what this is trying to show. (And this is just one example of the Outback’s poor software quality.)

OOP, FP, and encapsulating state

This article on has the flame title, Object-Oriented Programming: A Disaster Story. IMHO, a less-flamy but still accurate title would be, “OOP, FP, and the conundrum of encapsulating state.”

As someone who occasionally thinks of himself as an engineer as well as a software developer, I think you have to always look for what is the best solution to the problem, and sometimes that’s more along the lines of OOP, sometimes it’s FP, and sometimes it’s a hybrid.

For instance, when it comes to collection classes, I like the hybrid approach of the Scala collection classes where it appears that the functions are directly available on a collection instance, so I can write something like res = people.filter(age > 30). In other languages the filter function may not be directly available on a sequential collection class, so you have to import it and then write something like res = filter(people, age > 30). In either case you’re doing the same thing in the end, but the Scala approach “feels” better to me, and it’s also easier to read. (This example may just be syntactic sugar, but again, it’s easier to read, and the collections’ methods are a bit of a hybrid.)

As a better example of what I’m trying to say, OOP makes a lot of sense for rich GUIs, like Java Swing. Things like a JFrame, JDialog, JList, JTable, etc., all make a lot of sense in an OOP design. For instance, you create a JTable, the data is updated, users move columns around, and so on. OOP fits this very well.