Code As Communication

Why Tech Should Value the Liberal Arts Experience || Part Two

Purpose, Audience, and Context

In the introduction to this blog series, I mused on who my audience might be. This was mostly, like the rest of the introduction, a way of venting about the frustrations of changing careers and consequently seeing the not-insignificant number in front of “years of experience” vanish like a mirage from my resume and applications. It felt good. It might have even resonated with some English majors who like to code. But it was probably not particularly effective communication.

In rhetoric and composition, everything hinges on purpose, audience, and context. Before you decide what to say, you need to know why you’re talking, who you’re talking to, and where you’re talking. No duh, right? This should make pretty good sense to the average person. You don’t flirt at a funeral; you don’t bring pork to Passover. And yet, every semester, I had to plead with students to stop putting emojis in their emails to me.

It turns out it requires some conscious awareness to shape a message for a particular audience. Not just conscious thought, either — sometimes thinking is not enough. Sometimes you need some information. Sometimes you need to be exposed to a particular context to know what’s appropriate. Believe it or not, to be an effective writer, you have to be very good at bringing your conscious awareness to your context and audience, and you have to know how to find and incorporate the right information.

Stakeholders and Accessibility

When thinking about audience, one of our first considerations should be who is impacted. Whether it’s a message, a procedure, or a product, the things we put out in the world are likely to impact different people differently. One of the cardinal sins we can commit as producers of anything is to assume our intended audience is our only audience. There is rarely just one audience.

With their differing motives and levels of knowledge, these different audiences are generally referred to as “stakeholders.” The process of consciously considering these stakeholders and the stakes they hold is called “stakeholder analysis.” Writers are used to conducting this type of analysis while shaping their message, which makes a huge difference when writing code.

The most obvious place where we’re likely to notice this in code is accessibility features. Whether it’s providing descriptive alt-text in image tags, other ARIA landmarks for people using assistive technologies, or even just considering the cross-cultural comprehensibility of nonverbal icons and symbols, developers need to be conscious of different audiences, their specific needs, and varying contexts. Developers also need the language facility to describe an image or app component in context effectively.

Context & Conventions

Do you know why college papers are double-spaced? It’s because, once upon a time, your professors needed room for proofreading marks above and below your writing. In a world where most papers are submitted electronically and marked on a computer, do we need double-spacing? No. But it’s how your professors are used to seeing things. It saves them precious time because they recognize the lay of the land.

Similarly, why should we use snake_case vs. camelCase? Why should we give variables meaningful names instead of concise but cryptic ones like d for days or theList for an array (examples from Clean Code, Ch. 2)? Conversely, why can developers understand so readily that arr means array? Why do the sane among us use i and j for our loops when there are 24 other letters available to us? The answer is simple: because that’s how it’s done.

Most of the time, there were reasons people started doing things that way. For instance, camelCase solves a problem programmers had with complex variable names. We sometimes need more than one word to describe a variable. We can’t use spaces as the compiler will read spaces as delimiters, and simply mashing words together like acomplexvariablename isn’t very readable.

Some reasons are better than others. Most of them don’t matter anymore because they’re baked into the craft. A 2010 paper determined that readers can recognize snake_case faster than camelCase.A developer could argue from a technical perspective that all languages should be using snake_case and everyone else using JavaScript conventions is wrong. Good luck with that. It’s how things are done, how the new converse with the old. Writers are used to making concessions to convention, and developers should be too.

Readability

When designing a web application, it may be obvious that we need to consider our users. They are the audience that will consume our product. However, just as important and somewhat less obvious, we also need to consider other developers, not as consumers of our product but as readers of our code. In fact, you could say all code has two audiences: machines and developers. Both will need to be able to understand your instructions. Crafting code that considers both audiences requires conscious consideration. This is the main thesis of books like Clean Code. The fact that such books exist suggests it can’t go without saying. And writers who are trained in readability and consideration of audience will need very little convincing.