Are Right A Lot – Page 9 – Making Of Things

This Is A Post

By Jud | December 1, 2017 | Comments 0 Comment

A friend of mine suggested to me a few days ago that the recent Apple vulnerability might have been avoided if the (supposed) offending code had been commented. Perhaps, but perhaps not.

Code comments are a tricky business. Everyone knows they’re a “good thing” but that doesn’t mean every comment is a good one. Blindly them in quantity can actually make code legibility worse. I don’t go as far as Uncle Bob, however, who considers every comment “a failure to make the code self-explanatory.”

For me, a great rule of thumb is that code itself should be expressive enough to communicate the “what”, and comments should be used to explain the “why”. An example is instructive:

# If user is root and there is no root password, don't do the thing
if user == 'root' and password is None:
    dontDoTheThing()
else:
    doTheThing()

See how the comment doesn’t provide any information beyond what the code says? Pretty unhelpful. What a developer who’s asked to maintain this code needs is context, like the following:

# By default an installation of MacOS does not set a root password, thus root
# should never be used as a privileged account unless a password has been set
if user == 'root' and password is None:
    dontDoTheThing()
else:
    doTheThing()

Much better. A comment like that, and maybe Apple doesn’t end up in the headlines.

Phantom Fix

By Jud | October 9, 2017 | Comments 0 Comment

I’ve got good news and bad news. The good news is that the system is working now. The bad news is that we have no idea why.

The above scenario plays out regularly in the life of a software developer, and it’s infuriating. In some sense it’s worse for a problem to disappear without warning than it is for the problem to persist, because without reproducibility it’s nearly impossible to determine the actual cause of the issue.

This happened to me after losing a big chunk of my Saturday night. Essentially the issue fixed itself after several retries. No idea at all as to why, but at least I could finally go to bed.

The Herpes Of Version Control

By Jud | August 4, 2017 | Comments 1 comment

I love git. Truly. Once I got over the fear of learning something new and dove in, everything else paled in comparison. Maybe it’s just because I was a math major and directed acyclic graphs are cool. Maybe it’s because it everything about it makes sense (kinda like Python in that respect). Maybe because it’s the foundation behind open source software development sites like Github.

But this post is not about how much I love git, or why you should use it over the alternatives. It’s about one particular feature that drives me crazy at times, and that’s tags. Yes those littles things you use to mark important places along the development tree. They’re quick and easy to make (especially by CI tools that vomit them out daily), and really useful to have around. But the darn things are nearly impossible to get rid of.

It’s not that the implementation is confusing or doesn’t have logical justification (it does). But the distributed nature of git means they spread like wildfire, and are incredibly difficult to delete across all cloned repositories. You think you’ve gotten old ones deleted, and then some poor developer who hasn’t cleaned up his repo (or even worse, the local copy of a repo on your CI server) pushes and they all come back. Argh.

For a guy who is as anal-retentive as they come about keeping his repos tidy, tags are just the worst.

Ain’t No User Here

By Jud | July 5, 2017 | Comments 0 Comment

Here’s a new one. I was debugging a problem with a web server that hadn’t been used in a while that was allowing users to log in, but failing to perform a number of other functions (gotta love an API that happily returns a 200 OK even though it’s clearly not working because there’s no data in the response). No one could think of anything that had changed, but clearly something had.

After some spelunking through logs, I found some DB permissions errors. Obviously some DB calls were working, so that was odd, as I knew credentials were only specified in one place.

Another hour of research later, I discovered that MySQL views run as the user who created them, not the user who queries them. This actually makes sense for use cases where you want to give controlled read access to parts of the DB to a less-privileged user. Logically then, if that user is deleted, the view fails to run. And in this situation that’s exactly what happened.

There’s a number of lessons to be learned from this situation:

A user probably should fail to delete if it owns other objects in the database. Otherwise unexpected side-effects occur.
Accurate error messaging is essential to debugging. When trying to run the view, I got a simple “user does not have permission” error, which told me nothing about the underlying problem, which meant another hour or two of research. This goes for APIs especially. Please know when to use a 4XX vs. 5XX error especially, and even better learn the subtle differences between 502, 503, and 504, and when each should be used.
Don’t try to diagnose problems on Friday afternoons before holiday weekends. You’re asking for trouble.

Do The Right Thing

By Jud | June 30, 2017 | Comments 0 Comment

I love it when a programming language behaves in an unsurprising and helpful way. This is Python in a nutshell.

Consider the following situation I came across yesterday. I needed to pair off two lists. Naturally, Python has a built-in function for this:

x = [1, 2, 3]
y = ['a', 'b', 'c']
zip(x, y)
# [(1, 'a'), (2, 'b'), (3, 'c')]

But what happens if the lists are different lengths (as they were in my case)? Python does the logical thing, and stops with the shorter list:

x = [1, 2, 3]
y = ['a', 'b', 'c', 'd', 'e', 'f']
zip(x, y)
# [(1, 'a'), (2, 'b'), (3, 'c')]

This is exactly the behavior I needed, no special case handling required. Woot!

Gimme That Foot Gun

By Jud | June 22, 2017 | Comments 0 Comment

The past couple of days I wrote about the dangers of providing too much functionality. In a fit of cognitive dissonance I now want to contradict myself and demand dangerous power when it suits my needs.

I’ve been working the past week to get a particularly gnarly application running in a set of docker containers. There are over a dozen services, plus a Rabbit queue and a database. Many of the services do not handle database connection failures in a robust way. During my testing I wanted a simple way to ensure they waited a bit before trying to connect, as the database container needs a minute or so to seed itself and get ready for connections.

Unfortunately,docker-compose does not have any form of manual startup delay feature. This is by design, as the Docker team (rightly) argues that having services intolerant to connection failure is a bad thing. However, it’s frustrating to not have the power to do the wrong thing in the short term.

Then again, it turns out it wasn’t too tough to augment my compose file with a depends_on clause that includes a health check, which is a more reliable solution anyways.

User Error Isn’t

By Jud | June 1, 2017 | Comments 0 Comment

It happens to every developer at some point. You spend a bunch of time trying to determine the source of an urgent bug, only to find out the problem was caused by action or inaction of the user. It’s easy in that moment to be frustrated, but may I suggest a more circumspect path? It behooves a thoughtful developer in these moments to consider if the source of the user error was caused by poor design. Perhaps the button wasn’t in an obvious place, or the side effects of the command were not obvious, or the name of the feature didn’t describe the outcome. In many (even most) cases, user error is preventable with good design.

Yes it’s difficult, and perhaps impossible in some situations. But it is the high calling of the software engineer to design products in a way that a user almost subconsciously knows how to operate without error. Viewing design with this attitude saves a lot of frustration.

It might seem this is a counter argument to Not Even Mostly, but actually they go hand in hand. A user must be carefully listened to and considered, but sometimes they must also be guided into the features they really need, versus what they say they want. Do that hard work up front, and you’re more likely to have a system that minimizes the potential for mistakes.

Also, go read The Design Of Everyday Things.

Turn And Face The Strange

By Jud | May 22, 2017 | Comments 0 Comment

Writing requirements is hard. Rarely is enough thought put into them, and even when a lot of time is spent, gaps are inevitable. Thus the most important feature to build into a system’s architecture at the beginning is the ability to change. Without that, all other features will quickly become obsolete.

Every. Single. Time.

By Jud | May 11, 2017 | Comments 0 Comment

Want to know what happens if you don’t follow the Boy Scout Rule of software development? This.

That being said, it can be really easy to get into a vicious cycle of constant rewriting and never releasing. We’ll talk about that tomorrow.

Missing The Mark

By Jud | May 9, 2017 | Comments 0 Comment

Yesterday I made a broad claim about the applicability of various subjects to the task of software development. Today I want to give a specific example from the realm of theology.

The notion of sin is foundational to a number of world religions. Without belaboring the details or arguing the validity of any one definition, what cannot be disputed is that humans have been wrestling for a long time with their own limitations. Why is it that none of us are able to live up to our own ideals, let alone the ideals of a faith tradition? Why must it be that “nobody’s perfect”? To quote Saint Paul,

I do not understand my own actions. For I do not do what I want, but I do the very thing I hate . . . I have the desire to do what is right, but not the ability to carry it out.

Great stories confront us with the fickle imperfections of human nature as well. Is not human frailty and the conflict that arises from it the very foundation of an epic tale? Nothing proves this truth quite like “fiction”.

What does this have to do with software? Let me repeat myself: software is made by humans, and the results are subject to their constraints. That means you can expect both errors of omission and commission, and both unintentional mistakes (e.g. a developer fails to adequately review code) and deliberate laziness, cheating, pride, etc. One certainly hopes for few instances of the latter, but they do happen. It’s not just time you have to plan for.

A process must be designed to recover from its own imperfect implementation, else it is doomed to fail.