Author: Andrew Miner

Learning to appreciate the “out” group

Andrew MinerLeave a comment

A few weekends ago, my wife and I had some friends over for brunch. We had an entirely delightful time. We made breakfast together, swapped stories, joked around, and had a completely wonderful morning. As it turns out, my wife and I are white, and our friends are black. And, as much as I enjoy their company and admire their many accomplishments, I’ve realized I probably don’t appreciate them as much as they deserve.

I grew up in a very white community, and knew only one black person all the way through high school. She was my co-captain of the debate team, and, while we argued some (it was the debate team, after all), I thought very highly of her. But, in retrospect, I also don’t think I appreciated her as much as she deserved either.

However, in both cases, it wasn’t for being too sensitive of my friends’ skin color, but rather for being a little too color-blind.

It’s only been as an adult that the diversity of my group of friends has increased. Over the years, I’ve heard them talk about growing up, their school experiences, their professional experiences, and their adult lives. And only after hearing their stories that I’ve begun to really understand how to appreciate my friends fully. What you don’t really learn when you’ve always been part of the “in” group, is what it’s actually like to be part of the “out” group.

I’ll stop here a moment to say that while I’ve been part of enough “out” groups (e.g., nerdy, Jewish, bisexual) to have some inkling what it’s like, my experiences as part of those groups is far, far more mild than what I’ve heard from my black friends. So much so as to basically not be the same experience at all. I’ll also pause to say that I think the same applies to anyone who isn’t with the “in” group for whatever other reason (e.g., recent immigrants in an English-speaking business, women in engineering, men in nursing, or gay people in a conservative community).

Every company I’ve worked at has been overwhelmingly homogeneous on many axes. And, not all of the people I’ve worked with have much sensitivity toward “out” groups in general. So, when I start to imagine the sense of isolation it must engender being part of a small “out” group, I start to have an appreciation for the determination and self-confidence it must require to show up, and keep coming back: despite not fitting in with the larger group in some way.

And then, there are all the stories of people in an “out” group being passed over because they just don’t seem like management / leadership / whatever material. Or because they “don’t quite click as well” with the rest of the team, or whatever other squishy, hard-to-refute, but nevertheless-bullshit reason. One has to admire the grit and resolve it takes to decide to persevere through such an experience. And then you realize that every person you meet in such an “out” group may well have had to deal with that kind of thing personally.

Or maybe not. Perhaps they were lucky, and didn’t have those negative experiences. As always, making blanket assumptions about an individual based upon some inessential characteristic is dangerous. However, we all do it all the time: at least at first. You can only learn so much about a person in a first meeting, and it takes time to learn their actual history, struggles, and accomplishments. So, in the interval between meeting a person and deeply getting to know them, we all make lots of inferences from what little we do know.

My takeaway, then, is that in early stage of building a friendship with someone, it’s actually not fair to be as perfectly egalitarian as I’d like the world to become. For someone in an “out” group, the accomplishments I see and admire may very well have come at higher cost or effort than I would have expected. As a consequence, a person in that situation most likely deserves some extra credit for the extra friction they’ve had to overcome.

Of course, I fully expect this is all super obvious to anyone who isn’t part of one of the important “in” groups in their life. However, we of the “in” group are mostly so uncomfortable talking about this kind of thing, that it’s not at all obvious to us. I know I’m uncomfortable writing about it now. I feel more than a little blind that it’s taken me so long to become sensitive to it. It’s only after having enough conversations with my friends who are: black in a mostly white environment, female in a mostly male environment, gay in a mostly straight environment, etc. that the broader understanding has come to me.

So, in addition to the earlier takeaway, I’m left with an even more important lesson. It’s admirable to desire and work towards a world which has left racism, sexism, homophobia, etc. behind. However, until we get there, it’s not right to let the vision of that better world make us fail to give due recognition to people whose success comes a little (or a lot) harder because of the world we’re actually in.

Quora: What was the hardest situation you’ve faced?

Andrew MinerLeave a comment

I’ve been doing most of my writing on Quora these days, which has meant, of course, that I’ve been writing a lot less here. I’m going to start cross-posting some of the longer and more interesting questions & answers here so that this blog doesn’t completely go idle.

✧✧✧

I was 25 years old. My son was less than two months old, and my wife was no longer working (to stay with him). We had two car payments and a mortgage on our very first home. I’d just left a very well-paying job at IBM to take a chance with an exciting new job at a tiny, local company.

I got laid off three weeks before Christmas.

I remember it was a Friday, just before lunch. The company, a consulting agency, had just lost a major contract and needed to make cutbacks. It was also a cooperative (i.e., owned by the employees). I was a fairly recent hire, and hadn’t yet been made into a full member. So, despite being one of the more qualified people on staff, I was one of the ones they let go.

After spending the better part of the weekend in a panic, I figured the only thing to do was to start looking for a job. I went after it with a vengeance. Resumes sent, phone interviews, in-person interviews, and lots of time searching job boards and following up leads.

In the end, I landed at Amazon. It turned out to be one of the best jobs I’ve ever had. I learned how to be a manager, launched a major new feature on the website, and learned a ton about building large-scale websites.

I also learned one of the most important lessons of my life. No matter how bad things seem (and they seemed really, really bad at the moment), the best way to proceed is to evaluate your current options, pick the best one, and get started.

Building a Minecraft Modpack

Andrew MinerLeave a comment

I’ve been a huge fan of Minecraft for about seven years now. However, the basic game, while fun for a while, does tend to lose its interest after a while. Fortunately, there’s a huge universe of free add-ons, called “mods”, created by the community at large. In fact, there are so many that you couldn’t possibly just add them all to your game. So, the question is, how do you select which ones you’d like to have in your “mod pack”?

1. Choose a theme

I always start by choosing a theme. The easiest theme is to pick one mod you especially want to try out, and then select a bunch of other mods which complement that mod. So, for example, the last modpack I built started with a very realistic railroading mod called Immersive Railroading. From there, I picked a mod which adds a bunch of Victorian-age technology, some mods which add more food and crops, some which add more realistic biomes, and so forth. However, everything I added was required to fit the theme of Victorian-age railroading.

There are, of course, a lot of other ways to select themes. Perhaps you want a modpack based around space exploration, or one based upon super realistic wilderness survival, or exploring magical realms. Whatever you pick, let that be the guiding principle around all the rest of the choices you make, because there will be a lot of choices!

2. Select your Minecraft & Forge versions

Minecraft releases updates periodically which then requires the authors of each individual mod to make adjustments to their mods. For minor version updates, these are usually minor changes, but between major version updates, these can be quite substantial. For example, the changes between versions 1.7 and 1.8 were so substantial that the massive Lord of the Rings Mod is still only compatible for Minecraft 1.7.10, which was released in June 2014! All else being equal, my rule of thumb is to pick the newest version of Minecraft which has been out for 6 months. However, if a certain mod I really want to use is only available for older versions, I’ll fall back to the newest version it supports.

Nearly all mods these days rely on Minecraft Forge, a low-level interface for mod programmers to interface with the game itself. If you’re interested in building your own custom modpack, you’ll also need to pick which version of Forge to use. My rule of thumb here is to pick the most recent “stable” version available for my chosen Minecraft version.

3. Select candidate mods

The first phase of your many, many choices will be to pick out a bunch of mods which might be a good fit. I usually do this by going to the CurseForge Mods List, filtering by the Minecraft version I’m using, and sorting by most popular. I’ll briefly consider whether each mod might be a good fit with the theme of my modpack. If so, I’ll download the version which fits my Minecraft version.

In this phase, I almost always wind up with way more mods than I could reasonably fit into the modpack. I also wind up with a bunch of mods which might seem to fit the theme, but wind up not. Or, I might wind up with a bunch of mods which provide nearly identical functionality. Thats fine at this stage, but we’ll want to start narrowing things down in the next stage.

4. Mod exploration

Next, I’ll take each mod, one at a time, or in small groups which are closely related, and try them out. I often do this in creative mode so I can just tinker with the stuff the mod adds, and form my own ideas about how well it fits the modpack, and whether it’s a fun addition to the rest of the pack. I particularly try to weed out anything which seems too buggy, poorly balanced, or duplicates too much from another mod I like better.

As you’re working through this stage, you’ll often find a variety of errors and problems. Frequently, it will be that the mod you selected requires some other mod which you now need to go find and install. Sometimes, this will turn up a mod which requires a newer / older version of Forge than you’ve selected. In that case, you need to be very careful about upgrading / downgrading as you might run into even more problems with other mods which were happy with the version you already had!

I also try to make sure I fully understand what each mod does during this stage. This will often require tinkering with the config files to see what options are available, whether items I don’t like can be eliminated, and whether various things can be made easier or harder. I’m also looking for how well each mod interacts with related mods. For example, if I’m adding a mod which uses electrical power, I try to figure out if it can interact well with the primary mod(s) I’m using to provide it.

5. Down selection

By this point, I’ve got a pretty good idea of what each of the mods do, and how well they integrate with the other mods I’m considering. At this point, I’m trying to pick one and only one mod to serve each of a bunch of various functions in the game:

  • tweak the game’s UI
  • alter fundamental game dynamics
  • control terrain generation
  • control ore generation & add new ores
  • add additional biomes / control biome selection
  • add additional mobs: passive & active
  • additional trees, plants, flowers, crops, etc.
  • control mob spawning
  • add electrical power (if applicable)
  • add a system of magic (if applicable)
  • add helpful items to the game
  • customize recipes & remove items

Of course, one can’t always isolate each of these functions to a single mod, but the goal is to at least get down to a set which don’t directly compete with one another in strange ways (e.g., Dynamic Trees adds cool growing trees… but they don’t work with trees added by the Forestry mod).

This is the stage where you make the hard choices of which ones win out, and which get removed. It is often the case that a whole bunch of mods all work together very well, and some one mod has a bad interaction with just one of them. Sadly, this pretty much always means that you have to nix the “some one mod”.

6. Configuring by layers

If you take all the mods you’ve selected and activate them all at once, you pretty much always run into a mess of errors and incompatibilities. I like to tackle this problem one layer at a time. Using the list from step 5, I add in all the mods which deal with each item in the list at once, and then start up the game. Hopefully, you already worked out the hard crashes and incompatibles abck in step 4, so the problems you run into now are just ways in which these mods interact that you simply don’t like. Go back to the config files for each mod, and fine-tune the settings until that layer is working just as you like. Then proceed to the next layer.

With each layer that you get working to your satisfaction, backup your complete setup. It’s very easy to accidentally introduce problems which don’t become apparent for a while, so you definitely want to be able start over from the last thing you had working pretty often.

7. Play testing

Once you have the configs all set, it’s time to really test things out. There are a number of things I’m looking for at this stage. Some of them can be tested in a creative world (usually much faster and easier), but many can only be tested in survival (where the availability of resources and chains of recipes become important). Here’s a list of things I’m looking for as I do my play testing:

  • Is it easy to stay alive in survival through the first full day?
  • If certain resources are key to your various mods, are they readily accessible?
  • Are resources which are intended to be rare actually hard to find?
  • Do mods which are supposed to interact with one another actually do so successfully (e.g., do the HarvestCraft plants work with your Agricraft crop sticks)
  • Do mobs (active & passive) show up where and when they are supposed to, and in acceptable numbers?
  • Do you get crashes when you do anything, or visit certain places?
  • Does the overall world generation match your expectations / purposes for the modpack?

Ideally, you’ll be able to pull together a few people to play the modpack a bit on their own (both in creative and survival) before committing to using it on your server world.

✧✧✧

I hope this helps make the rather daunting process of putting together a substantial modpack a bit easier! It usually takes me about 20–30 hours to get all the way through this process for modpacks with around 100 mods in them. For an example of a modpack I put together this way, check out Brunel on GitHub. Enjoy!

Is blaming the victim always wrong?

Andrew Miner1 Comment

I’ve noticed this strange pattern of how people talk to one another about certain kinds of crimes: most especially rape against a female victim. The dialog usually starts with someone (almost always a man), saying something like “she was dressed too provocatively”, or “she shouldn’t have drunk so much”. This is immediately following by someone else (usually a woman) saying something like: “she should be able to dress however she wants; it doesn’t give anyone the right to rape her”.

First, I think we can all agree that there is no such thing as a right to rape anyone, for any reason, at any time. Doesn’t matter where they are, what they’ve been doing, how they’re dressed… full stop. No one is morally allowed to rape anyone else. If we can agree on that point, then we can also agree that it is in no way a woman’s fault for getting raped: no matter how she’s dressed or what she’s been doing.

It’s rapists who are at fault for raping. We should focus on teaching them not to rape, or, at the very least, providing some massive disincentives to do so. Right? Right. Of course. Rapists shouldn’t rape.

Now that we’ve got that settled… everyone will be fine, right?

Of course not.

Immoral people will always exist, and while we will always condemn immoral actions and try to educate / reform the people to commit them, that doesn’t actually do any good for someone already victimized by a criminal.

That raises the question of what are our moral obligations to looking after ourselves: especially in a dangerous situation. Let’s change the example. Let’s say I (a man) am walking through a bad part of town, at night, alone, in a smart suit with gold cufflinks. And, I get jumped. They take my wallet, cufflinks, and phone. They beat me up pretty well, and knock out a few teeth. Hell, let’s say I even get raped by one of the thugs, who happens to be gay. What responsibility do I bear for this event?

Clearly, I am not guilty of assault, robbery, or rape. I did none of those things, and the guilt for all of them lies completely on the thugs. Am I guilty of anything, then? Yes. I’m guilty of failing to properly assess the danger of my situation and taking sensible precautions. I have a moral responsibility to myself of looking out for my own person and property. In this case, I failed to do so.

It is crucial to differentiate between the level and nature of moral guilt here. The thugs are, without question, far more guilty of a much worse action. They deliberately, and purposefully, initiated violence against another person. On the other hand, I carelessly neglected my own safety. On the one hand, you have a egregious fault of morality, and on the other hand, a minor lapse—even if it had severe consequences. The difference in guilt here is so extreme as to practically bear no comparison.

I think this is the essence of the strange verbal exchange which started this essay. One mentality looks at a crime victim, and thinks the victim should have done more to protect themselves. The other looks and the criminal, and says we should prevent crime.

Both of these are correct stances. Both parties did something wrong. However, since these are not remotely equivalent wrongs, it is outrageous to focus one’s attention on the minor fault committed by the victim, instead of focusing on the immeasurably greater guilt of the criminal. And yet, one routinely hears more attention given to the women’s clothing, activities, or appearance after a rape than on the criminal.

So, yes, it can, sometimes, be proper to blame the victim, but absolutely not for the crime. At best they failed to take some necessary precaution (though even that doesn’t apply in most cases). They can—in no way—be blamed for the crime itself. The moral culpability for the crime is always 100% on the criminal.

Process is not a four-letter word

Andrew MinerLeave a comment

As a software engineer, I’ve worked with a lot of different development processes over the years, and I’m a pretty big fan of a number of them. Also, as a Getting Things Done (GTD) fan and advocate, I have a pretty rigorous process I’ve imposed on myself for doing my daily work. However, I constantly hear my colleagues decry “process” as an unnecessary burden, and look to eliminate it whenever possible. I think this attitude is somewhat mistaken at best, and actively harmful at worst.

Let me start, though, by being clear what I mean by “process”. A process is the means by which something gets done. Using that definition, if you get anything done at all, there was some process by which it happened. It could be a good process, a bad process, or even just plain trial and error. It’s still the way it got done.

So, process clearly isn’t actually the enemy here, since we all like to get things done. Really, the problem my colleagues are reacting to is having a bad process with too many unnecessary, laborious, or complicated steps. This is definitely a problem, but not the worst one you could have.

The worst is having no process at all. Of course, that’s not actually possible, so really what this means is that your process is made up as you go along, on the spur of the moment, each time you try to accomplish something. It may feel good not be restricted from tackling the job in whatever way occurs to you, but you’re very unlikely to take the optimal path from concept to completion. Instead, it’s very likely that pieces will be missed along the way, thrown back in haphazardly, not completed in time, or in the wrong order, and stakeholders will be unaware of what’s going on, or when to expect results.

The worst part of this ad-hoc process is that you’re doomed to repeat the same chaos every time you do it again. Since everything was made up on the spur of the moment, you’ll most likely wind up doing it a completely different way next time. Any lessons learned about what worked and what didn’t (even if you’re able to recall enough of what you did to try to analyze it), won’t be applicable the next time.

The essence of process improvement is repeatability. If you can reliably repeat the same sequence of steps each time, you now have a chance to: 1) clearly understand what you did, and 2) deliberately make changes the next time.

So, one step better than total chaos is what most people think of when you say “process”: a clunky, cumbersome, set of steps which create a lot of unnecessary busywork for those trying to accomplish the goal. I say this is still better than no process at all because it is repeatable. That means, you can tweak the process each time you repeat it to make it better.

The very best processes, of course, are those which only include exactly as many steps as are necessary to ensure the right work is done, done well, and all the right people know what’s going on at each step along the way. The problem is that it’s not always possible to predict what steps those are, and whether those will continue to be the right steps in the future (e.g., as the team grows, or the problem gets more complex).

That leads you to the real goal: to create a process which includes a means of improving the process itself. There are many examples of such processes (SCRUM, Kanban, etc.) when they are practiced well. In those cases, the built-in self-correcting nature of the process allows the details to change to adapt to new circumstances.

Of course, this ideal implies a few failure modes. One is to adopt a “we’ve always done it this way” sort of attitude which fails to allow for refinement, growth, or adaptation. Then, no matter how good or bad the process is at any given moment, you’ll never get better. And, as times change, the process will suit the current situation worse and worse.

A second failure mode is to change lots of thing with each repetition. It is very hard to successfully and consistently change a habit: even when you’re only trying to make one small change. This becomes nearly impossible when you pile on too many things at once. And, even if you managed to do it, it’s very difficult to judge which changes had what outcomes. Better to keep things simple and tackle one change at a time.

✧✧✧

As I said to start, a “process” is the means by which something gets done, and any time something gets done, there was a process by which that happened. Instead of treating “process” as a four-letter-word, I think we should embrace it. Whatever process you’re following for whatever goal you have, start by striving for repeatability, and then—bit by bit—keep making it better.

Organizing Members of a Class

Andrew MinerLeave a comment

In all the coding books I’ve read, I don’t recall any of them specifically talk about organizing the different members of a class.  However, in all the code I’ve read, the lack of any standard or order to how members are organized has been the single biggest obstacle to feeling at home with a new codebase.

The reason this matters so much has to do with our brain’s limited ability to keep track of a lot of things at once.  If we can only keep a few things in our head at a time, then it becomes hugely important for the readers of our code that we provide a hierarchy which doesn’t demand they understand more than a half-dozen or so sections at a time.  Moreover, it’s super important that these be immediately recognizable, and that they be in a consistent order so that they can be easily found.

Using Dividers to Create Hierarchy

The way I create an immediately recognizable sense of order is to create visual markers which clearly mark each section of a file. So, for example, let’s consider just the bare framework of a module in Python which contains two classes:

from some_package import a_module


############################################################

KNIGHTS_SAY = "Ni"
EXPECT_SPANISH_INQUISITION = False


############################################################

class TheMainObject(object):

    def __init__(self):
        # do constructor stuff

    # Properties #################################

    @property
    def alpha(self):
        return self._alpha

    @alpha.setter
    def alpha(self, value):
        self._alpha = value

    # Public Methods #############################

    def calculate(self):
        # calculate a value here

    # Private Methods ############################

    def _private_calculation(self):
        # do some private calculation

############################################################

class SomeHelperObject(object):

    # etc, ...

The first section (lines 1–3) contains all the imports. One of my favorite things about Python is that this gives you a complete listing of external dependencies, and an exact listing of where they are all coming from. Someone reading module can, in an instant, scan this very first section to see everything that’s coming in from the outside.

Next, I put in a full-width marker line with no label. As this indicates the top level of your hierarchy, it should be the full line width your team allows. That way, it’s immediately clear that you’re moving from one top-level part of the hierarchy to another when you see one of these lines.

The next section contains a few constants. These are clearly to be used across all the major sections of this module, and possibly even outside it.

Next, we have the class initialization section for the first class (lines 11–16). This is where the actual class declaration lives, along with any constructors. The semantic meaning of this section, while not explicitly labeled, it pretty clear: we’re setting up the class here.

Next, we have a subdivider labeled “Properties” followed by all of this class’s property declarations. If we had multiple properties here, they would each be listed in alphabetical order (more on this later). It’s important to note that this is a sub-divider, and is therefore shorter than the primary dividers since it represents the second level of the hierarchy. It’s important that it be enough shorter (15–20%) than the primary dividers that it be easy to see the difference even at a quick glance.

Next are the public methods, followed by private methods. As additional members of the second layer of the hierarchy, they use the same dividers. This pretty much covered your bases for most languages.

Sequencing and Sorting

With the visual hierarchy in place, then next thing I consider is the ordering of each element of the hierarchy. Since code is read far more than it is modified, my general approach here revolves around attempting to make the code as easy to read as possible. To that end, it’s important to keep the various levels of the hierarchy in as predictable and clear an order as possible.

For the top level of the hierarchy, we’re talking about sections for defining classes, constants, imports, and (depending upon your language) free-standing functions. In many languages, you’re required to list imports first, plus, that ordering has the advantage of making it clear what this code depends upon, so it’s useful to keep them up front. Next, I list the constants which are going to be used throughout this file. Next comes the primary class in the file (if there is one). Finally, come the sections for helper classes. In most cases, the part of the file you can readily see without scrolling down contains the imports, constants, and the start of the primary class section. So, in a single glance, the reader of the code can easily see what is the primary purpose of this file and what its dependencies are.

In the second level of the hierarchy, at least for a class, we’re mostly looking at various groupings of methods. I arrange these sections in order from most public to least. The reasoning is that a reader of the code is most likely to want to use the class, and then to inherit from it, and finally to actually change its implementation. This ordering addresses those various needs in order.

The third (and final) layer of the hierarchy consists of the members themselves. In 99.99% of cases, I simply sort these in alphabetical order. It is extremely tempting to try to order these in some “logical” order, but I have found that almost always leads to chaos. The reason is pretty simple. At first, the “logic” is pretty clear. The original author knows what the rational is, and puts things in that order. However, when the next author comes along, perhaps the logic of the ordering isn’t super clear. Maybe the next author is a little lazy. Perhaps they need to add a member which doesn’t fit into the logical scheme the other members follow. Inevitably, though, members start to be added wherever it “feels” like they seem to fit: or merely at the end of the list. Sooner or later, the only organizational scheme a new author can discern is: random.

Alphabetizing the list of members solves all these problems. It’s obvious from very brief inspection what the scheme is. That makes it obvious where to find an existing member, and where new ones should be added as there is only one correct place for each member. Moreover, it helps keep code diffs very easy to read and understand as there is a lot less movement of code from one change to another. Finally, it makes it extremely easy to tell whether a certain member is present or not (e.g., whether a certain method has been overridden).

✧✧✧

I have worked in at least a dozen different languages from PowerPC Assembly to C++ to Python to Go. In each one, I apply the principles of establishing visual hierarchy and creating an objectively correct ordering of elements in the file to ensure that the ultimate goal of making the code obvious and readable are satisfied. It doesn’t matter what the language is, whether it’s Object-Oriented, or what other conventions the language encourages. I find applying this framework makes my code immediately recognizable and earns praise from other developers for being among the most orderly and rational code they’ve ever seen.

✧✧✧

Want to see these techniques in practice? Check out some of my code at github.com/andrewminer.

What I’ve learned in 20 years with my wife

Andrew MinerLeave a comment

In a little over a year, my wife and I will have been married for 20 years. I was 21 years old when we got married, and 17 years old when we started dating. So, it’s been more than half of our lives that we’ve been together. And, unlike many couples we’ve known, we’re even more happy together now than we’ve ever been. I’ve been reflecting on why that is, and there are a number of things I attribute it to.

Respect

We both have a deep and reverent respect for one another. Ask anyone who knows us: we are two very different people. Instead of making this more difficult for us, though, I find that we often hold one another’s differing abilities in awe. To a large degree, I think that’s possible because we both have a great deal of respect for ourselves, and we’re able to view our partner’s superior talents with delight and admiration, rather than feeling threatened by them.

Likewise, we each have very different struggles. When one of us feels the need to improve ourselves in some way, the other is invariably sympathetic, honest in their feedback, and kind in that moment of vulnerability. And, when that person makes progress, the other is there to cheer them on, and applaud their success.

Listening

It’s terribly clichéd to say that the essence of a long-lived, successful relationship is communication, but that doesn’t mean it’s not true. What I always find dissatisfying about such advice, though, is that it’s not nearly specific enough. What isn’t said that that the most important part of communication is for each person to really, actively, listen when the other person is talking. This is most especially true when the other person is sharing an uncomfortable truth, either about themselves, or about the relationship.

If I’m the person doing the listening, that means that I am actively trying to understand my wife’s point of view before formulating one of my own. Most importantly, I keep quiet while she’s talking. At intervals, I might echo back what I think I’ve heard, and ask for her to correct anything I’ve misunderstood. I might ask clarifying questions where I’m uncertain. I’ll often ask her to elaborate on certain points I think may be connected.

Most especially, there are a number of things I do not do while I’m the person listening. First, I do not deny the truth or validity of her opinions and emotions. I might question facts, but if there’s any disagreement, we immediately turn to some source of actual evidence, or just let that point go. We both try to avoid the desire to be the one who was “right” and “won” the point. I also try not to jump in and “solve” the problem until she’s had her full say. Even then, I try (not always successfully), to ask her what sort of help (if any) she actually would like, before offering suggestions.

And, to be clear, we both play both roles here. There are plenty of times (more often, in fact), when I’m the one bothered by something, and I need someone to listen while I work through it aloud. In such times, my wife is invariably a patient and insightful listener.

Teamwork

Since the start of our relationship, we have faced the world as a united team. In fact, when we first got engaged at 18 and 20, we faced a fair amount of skepticism by standing together, and deciding how we jointly wanted to respond. Countless other examples have followed: when I got a new job out of state, deciding whether to have kids, and many others. No important decision is made without talking it over together first, and we value each other’s advice and opinion so well that we will often consult each other on relatively minor issues too.

Part of that teamwork, though, is trust in the other person to follow through as a member of the team. This applies both to what we say we will do (e.g., I look after our investments, while she looks after our health care), and what we say we won’t do (e.g., spend large sums of money, have relationships outside our marriage). This isn’t blind trust either: after all this time, we both have given and received ample evidence in big and small things that the other person is worthy of being trusted.

Deliberate Time Together

We are both people who get very engaged in our work, projects, and hobbies. We have careers, a house to manage, a son to raise, and more than enough to keep every hour of the day overflowing with things to do. However, pretty much since we both started working full time, we have deliberately maintained a weekly date. We’ve usually made it some kind joint lesson or another (e.g., flute, clarinet, ballroom dance, singing), or an activity we both enjoy (cooking, dining out). We generally change the activity at least once a year, either as circumstances change, or just to keep it from getting dull.

One of the most important aspects of these dates is the time surrounding the activity where we can talk. It has proven essential for us that there’s enough time that you get past the “How’s your day been?” level of questions and down to the longer-term, difficult, or uncomfortable conversations. I remember that a lot of these happened around when I came out. Over the past couple weeks, these have been about our son’s transition into a simultaneous High School / College program where he’s struggling a bit. These are the kinds of conversations which cannot happen in the ordinary rush of day-to-day life, and we have found it essential to deliberately carve out space to make sure they can happen.

Deliberate Time Apart

Just as we deliberately plan time together, we also deliberately give each other space to be individuals. Not all activities, friends, and hobbies need to be shared. Again, this seems obvious, but I also see plenty of couples where one person feels left out or hurt when their partner wants to go do something on their own.

As an example, when our son was a toddler, and my wife was the stay-at-home mom, there came a point where I could tell that she was very much in need of some time off. So, I planned a trip which had her drive away, alone, in her car with a box of envelopes with numbers on them. This lead her through a scavenger hunt to pick up some of her favorite treats on the way to a weekend stay in a lonely B&B on the coast of Washington state. She had nothing to do, no obligations to anyone, and everything planned out for her in advance. A few months later, after I’d just gotten a new MINI Cooper and finished a stressful project at work, she arranged a similar trip for me high up in the back roads of the Cascade mountains with a new book. We were each thrilled with our own trips, but would not have enjoyed the other person’s.

As another example, I enjoy playing video games (something I share with my son), but they make her motion sick. She loves singing in a chorus, but that’s just not my thing. Every once in a rare while, we’ll share in those activities, but mostly we’re very supportive of the other person spending some time alone with their hobby.

Physical Intimacy

Yes, sex is definitely important in our relationship. However, there’s more to it than that. Anyone who has seen us together will attest that we are constantly touching each other in small, loving ways which have nothing to do with sex. Hugs, kisses, holding hands, snuggling in our big armchair to watch a movie, or even just a light caress as we walk past one another are constant and daily occurrences. This is a constant reinforcement of the sense of closeness and intimacy we share with our favorite person.

As for actual sex, we apply the principles above. We have different levels of interest at different times, we each react physically to different things, and we each are different in desire to try new things. We negotiate those differences by respecting each other’s limits (while still asking for what we each want), actively listening to what the other person likes, and being deliberate in setting aside time to make sure that part of our relationship doesn’t get buried in the daily grind.

✧✧✧

I’m positive there are a bunch of things I’m missing, but I feel like these are the most important ones. Of course, these are the things I think have made the most difference in our relationship with our particular personalities. I suspect, though, that most couples will find these principles apply to them as well.

Getting the most from your log file

Andrew MinerLeave a comment

Think back on the last time you urgently needed to figure out what a live, production piece of software was doing. It’s very likely that nearly the first thing you did was to pull up it’s log. It’s also very likely that the majority of the content was either useless, unintelligible, or flat-out misleading.

The reason most logs fall into this state is that they are a piece-meal accumulation of statements which were thrown in over time. This is a problem because the only possible reason to waste the computer’s resources producing them is to be as correct, intelligible, and useful as possible. In short, log files should be explicitly written for consumption by people.

As with anything else, clear writing requires the author to carefully select the content, and to create it with the reader in mind. In the case of log files, we know other engineers (or scripts they write) are going to read them, and they are going to want to know how the server has been behaving. Moreover, no one reads log files unless something is going wrong. Therefore, log files should be written to make it as easy as possible to debug why a server isn’t behaving as it should. To that end, here are a few specific guidelines I’ve found most useful:

Make it easy to track down errors

It should go without saying, but it is imperative to make it as easy as possible to identify where – in the code – an error occurred. In Java this may be printing out the stack trace; in C/C++/Objective-C, this may be using the __FILE__ and __LINE__ macros. Most languages have some similar feature. Along these same lines, try to avoid having logging statements which look too much alike. This makes it easy to misinterpret the log, and completely identical statements make it impossible to know exactly where an error occurred.

Log all inputs and outputs

The fastest way to track down the reasons for strange output is to know whether the input was strange, too. This is especially true for a server (i.e. a malformed request), but it applies to other programs as well, provided you have a sufficiently broad view of “inputs” and “outputs”.

I consider an input/output to be any data which enters (or leaves) the program’s runtime context. This includes: user input (mouse/keyboard events and the like), files read/written to disk, data sent/received on a socket, or requests/results from a database query. I recommend at least logging something every time such an input or output occurs, and if reasonable, the actual content itself.

Logging inputs and outputs provides a number of major benefits. First, you know exactly what the system was asked to do. This allows you to immediately know whether a problem is in your program or outside of it. Second, it gives you a pretty clear indication of what will reproduce a problem (if there is one). Finally, it allows you to report errors to the owners of the “other” system in case you received an unexpected input.

Record how long it takes

Errors are frequently just that a system is taking too long to respond. Being able to quantify the time required for each request is an extremely valuable way to isolate the problem. However, it is not sufficient to simply record how long your system took. You must also record timings for each request you make outside of your application’s runtime context. That way, you’ll know right away if your program appears slow because it’s waiting for something else: whether it’s a web service call or reading a file from disk.

Don’t log the expected case

If something is supposed to happen, you generally don’t need to know about in the log (unless it’s one of the things mentioned above). Bear in mind that no one is interested in reading a program’s log unless the program is misbehaving. At that point, the person wants to read as little of the log as possible. Including a lot of “business as usual” statements in the log only makes the process more difficult.

Use log levels to indicate action required

Since a log file’s purpose is to assist in figuring out why a program isn’t running correctly, it’s extremely valuable to use log levels to indicate how “badly” things are going. I recommend thinking of the action required as a guide to what log level to use:

  • FATAL: page someone immediately
  • ERROR: send an email immediately
  • WARN: send in a daily report
  • INFO: include for later debugging purposes

Depending upon your logging system, the various levels often have different names, but these should map to whatever you use. Even if you don’t actually have an automated system to page people based upon your log file, it’s extremely clarifying to think about each level in these terms.

Make it easy to parse

Finally, bear in mind that most uses of a log file involve searching or parsing them using automated tools. Be sure to include standard fields in each line so that these tools can easily extract information from them. Here are some examples of what fields you may want to include:

  • time (down to milliseconds and time zone)
  • the number of the line in the log statement (to ensure each line is unique)
  • the current thread
  • the current user ID / IP address / other client-related identifier
  • the log level
  • the file/class

There’s a lot more to be said on logging, but if every log I’ve read implemented these few principles, my life would have been a lot easier. If there’s some piece of wisdom that’s too good to be missed, feel free to add it in the comments!

The Right Size for a Method

Andrew MinerLeave a comment

One occasionally hears of some programming zealot who swears up and down that methods should be kept to n lines or less. The actual value may vary, but the arbitrary nature of the claim remains. However, there is a kernel of truth there, and it has to do with preserving unit economy.

We all know that the longer a method is, the more we have to keep in our minds to understand it. There are likely to be more local variables, more conditional statements, more exceptions caught and thrown, and more side-effects of all those lines of code. Furthermore, the problem grows faster and faster as there are more lines of code since they all potentially can have an impact on one another. Keeping methods short has a disproportionately large benefit.

Of course, claiming that there’s some absolute “correct” number is clearly nonsensical. The same number of lines in C, Lisp, Java, Assembler, or Ruby will accomplish radically different things, and even how one legitimately counts lines will change dramatically. What does not change, though, is the need for the reader (and author) of the code to understand it as a whole. To this end, one should strive to keep the number of discrete tasks a method accomplishes to within the range of what people generally can remember at once: between one and six.

Each task within a method may have several lines of code of its own; how many tends to vary widely. Consider the process of reading a series of rows from a database. There may be a task to establish a database connection, another to create the query, another to read the values, and perhaps one more to close everything down. Each of these may be composed of anywhere from one to many lines of code.

Tasks may even have subtasks. Consider the example of building a login dialog. At some point, there is likely to be some code which creates a variety of controls, and places them on the screen (e.g. an image control for the company logo, a text field to capture the user name, etc). In the method which does this, one may consider the process of creating the components a single task which has a number of subtasks: one for each component.

In both cases, the important consideration is how organizing the method into tasks and subtasks helps preserve unit economy. By creating tasks which have strong cohesion (i.e. you can name what that group of code does) and loose coupling (i.e. you can actually separate that group of lines from the others), you give the reader ready-made abstractions within your method. In the first example, the reader can readily tell that there’s a section for setting up the connection, and be able to mentally file that away as one unit without the need to remember each line of code in it. In the latter example, the reader can categorize the series of UI element creation subtasks as a single “build all the UI components” task, and again be able to abstract the entire thing away under a single unit. Even if there are a dozen or more individual components, it still can be considered a single task, that is, a single mental unit.

This ability to create abstractions within a single method is why there is no absolute “right” size for a method. Since grouping like things into tasks and subtasks preserves the reader’s (and author’s) unit economy, it is quite possible to have a method which is very long in absolute terms, and still quite comprehensible. It also implies that a fairly short method can be “too long” if it fails to provide this kind of mental structure. The proper length will always be determined by the amount of units (tasks) which one has to keep in mind, and the complexity of how those tasks are interrelated.

Response to “Diversity and Justice”

Andrew MinerLeave a comment

A day or so after publishing Diversity and Justice, I received the following comment from a female acquaintance:

I appreciate you offering this patch! Some code comments from a more senior developer in the area:


Good start with “there are traits which matter and traits which don’t”! Your error is that you’re assuming the only variables that matter are the ones in your Engineering function, but you’re using classes that are defined globally. Banana-gorilla-jungle stuff. 


That’s why you’ve got the common misconception “since ‘female’ doesn’t directly come into play in ‘Engineer’, an object descended from both ‘female’ and ‘Engineer’ is the same as an object descended from both ‘male’ and ‘Engineer’.” In fact, because female is a trait that matters globally, anyone in the female Engineer group has had to pass through a filtering function “stand_up_to_assumption_of_incompetence” that requires that engineer be confident in their knowledge, or patient, or stubborn, or lucky, or sociopathic, or possessing some other extra trait; most of which are favorable for Engineering prowess.

If you have two pools of engineers and one is pre-screened, it makes logical sense to exhaust the pre-screened pool before turning to the random pool!

Also, most people who work in this field use a fork of the Justice framework that comes with a bunch of open source tools specifically for working with these filtering functions; like Feminism or Anti-Racism.

Again, thanks for weighing in on the project!

To be honest, my first reaction was to feel annoyed and patronized. I was tempted to ignore the comment and just move along with my day. But I couldn’t, in good conscious, let it go so easily.

First, while my first reaction was to view this as a “negative” comment, I’m not 100% sure that was the intention. I’m perfectly willing to accept a well-reasoned and friendly rebuttal to my ideas. In fact, that’s one of the reasons I publish things publicly, instead of just keeping them to myself. However, I’m a lot less interested in debating a point with someone who is already hostile. But, knowing the person who posted the comment (I attended her wedding!), and being good friends with her husband, I am much more willing to give her the benefit of the doubt as to her intentions.

Second, if you look past the tone of the message to its actual argument, I think there’s validity to her point. That is, any woman who is still in the software field after any length of time has had to put up with a certain amount of bullshit which gives her a certain talent and toughness above the average candidate. That being the case, you could consider female candidates even more attractive than the average male candidate. I think there’s some truth there, and I was even considering various similar ideas when I wrote the original article. But, to keep things concise, I decided to exclude them.

However, the reason I ultimately decided to respond with a new post is because I think this comment actually demonstrates the third part of the trap, as I outlined in my original post:

Finally, it’s a trap for everyone trying to correct the problem. By framing the situation as one group oppressing the other, it creates a powerful “us vs. them” mentality which is hard to overcome. People in the minority group are tempted to identify all people in the majority group as oppressors. Allies in the majority group feel unfairly accused, and are less likely to want to remain allies. Progress in correcting the situation is impeded to no one’s benefit.

Andrew Miner

Whether it was the commenter’s intention or not, my reaction to the comment was exactly what I described: an ally who was being unfairly attacked. To put it more bluntly, I felt I was effectively being told: “Get out of here; you don’t know what you’re talking about.” with a little pat on the head for at least trying not to be a sexist asshole.

✧✧✧

While I wish the comment were more unambiguously friendly in tone, I appreciate the time my acquaintance took to write it, and I think she makes a good point. I would prefer, though, if we all were to follow Lori Lakin Hutcherson’s admirable example when she (a black woman) responded to her friend (a white man) who was struggling with the idea of “white privilege”:

I truly thank you for wanting to understand what you are having a hard time understanding… because I realized many of my friends—especially the white ones—have no idea what I’ve experienced/dealt with…

Lori Lakin Hutcherson

Lori embraced her friend’s attempt to figure things out and be an ally. She was willing to accept his professed good intention (despite his ignorance), and help him understand her own point of view in a friendly, sincere, and very powerfully honest way. I think we should all aspire to follow her example.