Background and context for the Software Development Guidelines
Drew LeskeIt can take a while to learn a team’s culture, and there’s no quick solve for that: it’s the culmination not only of the group’s shared experience but the years of lived experience each individual brings in, and it evolves over time and is always unique. Expected practice, on the other hand, can and should be clarified–and if your team culture has “inclusion” as a core tenet, then setting clear expectations is essential to keeping everybody on the same page.
Note: This log entry is mostly cut and pasted from the Software Development Guidelines. It didn’t live up to the “this needs to be short” statement, so they’ve been split up. Most of these words were originally written in January 2022, within weeks of me starting this role. We’ve looked at it every once in a while and I have little to update apart from tone and tightening. What we do have that’s new is some language-specific advice.
I have each member of the team read the document as one of their first tasks, and have them review it again and provide practical feedback as one of their last.
First, let’s clarify intention: these are not rules. While I don’t believe rules are made to be broken, I also don’t believe they’re made to restrict people from doing good things, and it’s generally impossible to foresee all possible scenarios when devising them.
I’m also reminded of a professor of tech writing I had many moons ago, who taught me one of the most valuable lessons about writing.
Understand the rules. Break them if you have to, but know why you’re breaking them.
So let’s consider them guidelines.
Second, this needs to be short. The last thing I want to do is squash an excited new team member’s spirit with an indigestible list of commandments.
Third, each guideline needs a justification. In an early job developing for a large engineering department, there was a well-designed coding standard all employees were expected to follow (and if they didn’t, code reviews would get them in order). I kept a copy of the standards for years, although I rarely had the opportunity to make use of them, because they were an excellent model of how such things should be written. Each standard was clearly written in simple language, followed by a description of why this standard was set.
In my experience, most people are okay with following a rule, even if they disagree with it, if they are given a reasonable justification, even if they disagree at some level with the justification.
Here’s a personal example from the same job, when the coding standards were
updated for a major new undertaking involving C++ (previously the department
was assembler and C). Class and member naming would use camel case instead of
underscores, in most cases, including acronyms. So a member variable
describing the user’s universally unique identifier (UUID) might be named
myPersonalUuid. This drove me nuts at first; I wanted to name it
myPersonalUUID. But if the acronym appears in the middle of the variable
name, the separation of terms indicated by the camel casing is muddied.
I understood this, but I just didn’t like it. Soon enough though I realized that I was being silly. Readability and consistency are fundamental in collaborative work, the rule made sense, and at worst, it was the lesser of two evils. I accepted it, and although I twitched a bit using it for a couple of days, I got used to it.
Here’s another example from right now. In my spare time, I’m messing about with Go (the language). It uses tabs instead of spaces–and I thought Python’s PEP 8 standard of 4 spaces for indentation was way too much screen real estate. Tabs is like, what what WHAAAT–at least for me.
But as Go language developers explain for another issue, on braces and semicolons:
More important–much more important–the advantages of a single, programmatically mandated format for all Go programs greatly outweigh any perceived disadvantages of the particular style.
(Although, of course, this could have been smugly written by whoever set their personal preference as the standard for the new language. I can’t think of a better reason to invent a new language at this point, to be honest.)