A Writer's Guide to Coding

Once upon a time, I was a writer. Not in the way I am now, writing technical(ish) blog articles and code, but a writer of essays, short stories, movies reviews, and news articles. My love of the craft has never gone away, and I've learned to apply the best practices from those days to my coding.

A colleague of mine pointed out that mine is far from the typical career path and suggested I write a bit about my approach to code. So here we go!

Consider Your Audience

One of the first rules of writing anything is to think of who you're writing for. When I was writing movie reviews, for example, I tended to frame it like I was trying to convince a good friend to watch (or avoid) the movie in question. I like to make my friends laugh so I usually worked in as many jokes as possible. I also avoided deep technical dives into camera angles and shot composition because most of my friends don't care about that kind of thing.

When writing this article, I'm thinking more of my colleague who was curious about my thought process when coding and my developer (read engineer if American) friends who maybe want to make their code a bit clearer. Since I'm thinking it'll be technical people mostly reading this, I'll likely include some examples.

So what about code? There are two people I always try to keep in mind:

1. The junior dev whose first ticket is to bug hunt or expand what I've written
2. Future Me, five years from now, when I've completely forgotten the domain and someone asks me to explain what I was doing and why

Those two people actually have a lot in common. They aren't here now, so I can't assume they know much about the feature or requirements. They're at least somewhat technically capable, so they'll be a bit annoyed or insulted if there's too much hand-holding. They're (probably) good people, so I don't want to make their lives harder than they need to be!

Keeping these people in mind, there's another set of guidelines I try to follow.

Accessibility

That's right, fam! Accessibility ain't just for the User Interface anymore!

The main sections of the Web Content Accessibility Guidelines (WCAG) that we care about here are those concerning making things readable. When it comes to code, that means making sure your function and variable names use commonly understood words and few (if any) acronyms.

Why bother? Well, the thing about that junior dev we're keeping in mind is that we have no idea if English is their first language. Even if it is, we don't know their regional dialect or educational background. By keeping to the "Grade 8 reading level" goal when naming things and writing comments, we're trying to reduce the amount of brain power they're using to translate so they have more available to understand the code.

Another thing we don't know about that junior dev or Future You? Whether or not they're blind or visually impaired. Variable names that are a single letter or an acronym are often painful when using screen readers, and if you need to increase your font dramatically you can easily lose sight of the initial instantiation that tells you what that letter stands for.

I promised an example, so here's some made up SQL to show why this can be such a problem. I want you to increase your zoom to 400% (yes, I have seen devs need this level of zoom) and figure out what each of the following columns refer to.

SELECT DISTINCT
s.ID,
s.name,
st.firstName,
st.lastName,
st.middleName,
st.ID,
s.grade,
c.name,
c.ID,
p.name,
p.time
FROM school s
INNER JOIN student st ON st.schoolID = s.ID
INNER JOIN studentCourse stc ON stc.StudentID = st.ID
INNER JOIN course c ON c.ID = stc.CourseID
INNER JOIN coursePeriod cp ON c.ID = cp.CourseID
INNER JOIN Period p ON p.ID = cp.PeriodID
WHERE st.endDate <= GETDATE()        

Did you notice the mistake? The grade column is coming from the school record instead of the student record, which is very probably wrong. It might be obvious enough in this small example, but this is an extremely simple SELECT statement. Add a few PIVOTs, some WINDOW functions, and a couple of common table expressions (CTEs) and it's very easy to get lost in the single letter aliases.

That said, I can be as lazy as any other developer and will use single letters when it doesn't matter much or the only use is within a few lines of the original alias. That coursePeriod table, for example, is just a join table, so there isn't really as much need for it to be easily readable. This is how I would normally write a query like this:

SELECT DISTINCT
school.ID,
school.name,
currentStudent.firstName,
currentStudent.lastName,
currentStudent.middleName,
currentStudent.ID,
school.grade,
course.name,
course.ID,
period.name,
period.time
FROM school
INNER JOIN student currentStudent ON currentStudent.schoolID = school.ID
INNER JOIN studentCourse stc ON stc.StudentID = currentStudent.ID
INNER JOIN course ON ccourse.ID = stc.CourseID
INNER JOIN coursePeriod cp ON ccourse.ID = cp.CourseID
INNER JOIN Period ON period.ID = cp.PeriodID
WHERE currentStudent.endDate <= GETDATE()        

I left the mistake in just to show how glaringly obvious it is now. Using currentStudent as an alias is nice, too, since it makes it clear that we're limiting that table in a specific way.

Depending on how hard I found the initial read of the code, it's not uncommon for me to rename table aliases or variables like this. This is one of those things that should only take a few minutes, can save the next person a lot of time, and has no risk since it doesn't affect implementation. There's one other thing that can save the next person a lot of time.

Comments

As someone who has been in way too many discussions about how and when and why to comment, I'm not going to go on about this too much. Every team seems to have its own culture around commenting the code, from extremely regimented templates to "nah". I tend towards the latter, but I make exceptions if the answer is yes to any of these questions:

1. Am I doing something that goes against our team's conventions for a specific reason?
2. Would it take more than a few minutes to understand why the code is the way it is?
3. Am I fixing a bug that took more than a few hours to figure out?

I recently had to add a comment after answering yes to all three when I used BULK INSERT to pull a JSON file into our database for parsing.

First, our normal convention for file parsing in SQL is to use OPENROWSET, which works like a charm with CSVs and format files. Second, unless you knew what was being fixed it wouldn't be clear why loading a JSON blob into a table, then parsing from that table is better than parsing that table directly. Finally, it took way longer than I wanted to figure out that OPENROWSET in Microsoft SQL Server 2016 was mangling special characters and that BULK INSERT was the only way around the problem.

I obviously don't want that hypothetical junior or Future Me to see the difference and change it back, and I'd like the reminder the next time I'm parsing JSON files. So, right above my BULK INSERT, a simple comment.

Use BULK INSERT to preserve accents and special characters from JSON files.

Depending on the situation I might also include a link to a requirements file, or specific API documentation that discusses the bug, or maybe even the ticket if it's a really weird issue.

The main goal, always, is to make reading the code as easy a possible so we have more energy to focus on the actual task. Coding like a writer takes a little bit of extra effort, but isn't the happiness of Future You worth it?