Editing code (a mental model)
Hey, hi, hello. My name is Ben and I come from a background in writing things that are not code. Today I wanted to talk about the different kinds of editing you can do with more traditional text, and how I think this can be a useful model for subdividing your code tasks.
By having a clearer idea of what you are trying to change on a pass over code to review it, I’m hoping you can give better outcomes from reviews.
What even is editing?
Editing is a subtask of writing which is essentially focused on going from ‘I have a bunch of text what I wrote’ to ‘here is a well structured and grammatically correct piece of writing.’ It, in turn requires thinking about a bunch of different concerns for your writing.
Is this just refactoring?
Maybe, but I don’t think so. Firstly, editing is something you do in the initial writing, where a developer may do refactoring, but I’m going to propose this is a form of editing.
I am going to define refactoring as ‘taking code that someone else has written (or you wrote some time ago), and editing it to better suit current needs’. Refactoring may just be a subset of editing, but I’m not going to be talking about it here. Instead, I’m focusing on kinds of editing.
Right, let’s dive into some types of editing!
Structural Edits
A structural edit is one where the goal is to reformat the entire text. At this point, you want to make sure that entire sections are in the right order, and that the flow makes sense. The exact content of sections isn’t important to look at, just the impression. Structural edits are most important when the shape of the original has changed significantly.
Structural edits should stay away from anything too micro that a change in structure might completely wipe away, and unfilled sections or placeholder names can be ignored until later.
In code, I would put a structural edit as editing what functions are available to a file, and what the shape of calls to produce a result are. This is the architecture-level decision making, though I would also extend it down to the more granular part of editing function signatures. Deciding what data different parts should have access to and how to pass it around would also be a structural concern.
Content Edits
Content edits are when you start getting into greater details. How many sentences are in each paragraph? Does each paragraph contain a central idea? How well is the idea delivered to the reader?
Content edits start to get you into the weeds, and towards caring about individual words, but a lot of very technical decisions still might not need to be made.
At the end of a content edit, you should have something you can print.
For code, a content edit would be concerned with editing the implementation, and making decisions around how best to achieve the goals laid out by the structure.
Copy Edits
Copy editing is editing focused on the granular details. This will include things such as spelling, grammar, and individual word choices.
This is not to say that these should never be corrected before this, but that there should be a pass specifically for copy checking after everything else is nailed in place. A copy edit is what will move a piece of writing from being messy to reading as super profesh, and ready for anyone to pick up and read.
Without good copy-editing, a very well thought-out piece of writing can become hard to decipher.
The coding equivalent of this is really sweating the small details. Precise names for every variable, ordering of conditionals, and a whole bunch of formatting work. When are you using const and let? Are names consistent between functions?
While a lot of copy-editing gets done for us as js developers (prettier and eslint do a lot of work), without taking the time to think about how readable our code is, we’ll have fallen into the trap of bad copy-editing.
Are you suggesting we edit every file three times?
Not necessarily, though it probably wouldn’t hurt. The goal is to be more mindful about what precisely you want to know when you are reading through something. If the structure is all wrong, all the contents might be thrown out, so don’t spend forever commenting on it. If the content needs to be rewritten, there’s no need to worry about making sure the indentation is correct.
Define what you are trying to achieve when you are editing code, and let that guide where you are focusing.