Tales of a #SurfaceGopher — How I take notes as I code
Taking notes isn’t just important when you are in school. In software engineering, taking notes is incredibly useful for keeping track of what you’re doing. Individually, good notes can help you keep a more focused, organized workflow, and working on teams you can use your notes to formulate your ideas to communicate them more clearly. This is useful in a wide variety of situations.
If your team is adopting a new technology, you’ll be hitting the books (or the blog posts), so your notes will help you keep track of the concepts that are important to know. Additionally, most engineering problems on the job have multiple possible solutions, so you’ll want to keep track of the pros and cons of each one to make clearer documentation and issue descriptions, as well as to effectively communicate your ideas in team planning discussions. And if you’re working on a part of the codebase you only visit a few times a month, you’re reviewing someone’s code there, or you’re coming back to a task that got iceboxed a few weeks ago, quickly regaining the context from the last time you were there will help you get back up to speed faster.
At work, as well as when I do projects on the side in my free time, I handwrite my notes, focusing on speed and clarity. My goal taking notes is that in addition to having a fast reference to the code I’m jumping through and a way to keep track of things that need to get done, I am able to capture my thought process. Retaining that context is really helpful for having notes that are easy to understand without having to write everything down.
Before we dive into my technique, it’s important to note that this is only one notetaking style, and that there is no wrong strategy; the one you pick should be ergonomic for how you work so the notetaking doesn’t get in your way, and it should be easy for you to read. My style, for example, has influences from how I took notes in high school, this style from Studytee, this style by Mariana’s Study Corner, and bullet journaling, but your style might have a different set of influences. Whatever it is, no hatin’ here!
Abbreviations
In school, they most likely taught not to write down everything the teacher says, and instead use abbreviations and acronyms. This technique I used heavily in school, but I found that in college, where exams covered more material, this made reviewing for finals hard because I would forget what an abbreviation meant. That said, I do still find having a core set of regularly-used symbols and shorthands useful for writing notes faster.
From math and science classes, I use ~ for “similar”, ∀ as “for all”, “all”, and as a loop symbol, and Δ (delta) to refer to changes. From COMP 105, my programming languages class at Tufts, I use the Greek letters Φ and λ (phi lambda) for function, τ and κ (tau and kappa) for type and kind, and I also added θ (theta) for talking about threads in multithreaded code. I also use ð (eth, from Icelandic) to write common th- words faster, and I have a symbol that’s half a lowercase d and half a lowercase f for “default”.
Other symbols, abbreviations, and acronyms come and go, and whether or not they stick depends on whether or not they’re regularly used; if they’re not, you’ll want to go back and write down what they stand for. The important thing with abbreviations and symbols isn’t which ones you pick or that they put less ink on the paper, but that they make things faster to write without a big sacrifice to readability.
Colors
I prefer handwriting my notes over typing not only because it’s more freeform and the low friction with gel pens is so satisfying, but because I think handwriting puts more neurons to work incorporating knowledge (if anyone knows the neuroscience behind this, please send a link and I’ll give you a shoutout). Also as Studytee mentioned in her video, switching colors to write down an important term makes it easier to remember.
What I go for with colors is that both the information I’m processing, and my thoughts on it at the time, are easy to retrieve quickly. I use a black pen for most of my writing, and switch to blue if there’s an idea I have for something worth trying out in my code, or if there’s a term I know is going to be important (because blue’s clues). I also sometimes put those ideas I want to try or explore on their own lines on the paper in blue so they stand out more.
Pitfalls, concerns, crash logs, and potential or confirmed bugs I come across, I write about in red with a ⚠️ emoji and try to leave plenty of detail. At work, you’ll want that context on bugs and other concerns in your notes so you can bring that up in design meetings, incident response discussions/postmortems, or if weeks later the implementation path your team picked isn’t working out and you need to backtrack. This is also useful on side projects, where you might be coming back from many days or weeks off the project and you need to see what your concerns were the last time you were coding it.
Finally, something I found in school taking notes, and why I found English class so hard, is that it’s hard to know whether or not a piece of information is important the first time you see it. So to get around that, I have a highlighter ready so I can mark a term as important if I had previously written it in black. You can use underlining too, but I find highlighter to be more visible. This has been especially useful to me learning frontend for side projects, where there are many packages to work with, so I need to keep track of a lot of concepts and figure out which ones are the most important.
Sectioning
As I mentioned, something I really like about handwriting my notes is that it’s more freeform, so I can add sections and boxes anywhere on the paper. In general, I try to box my code snippets and diagrams so they stand out more. And if there’s something I think might be the fix for a bug, but I’m not sure if it is yet, I write down my idea in blue and box it with a squiggly line. Block quotes are another thing worth giving their own line; if there’s a conversation at work, a Slack message, or something you read that really clarifies something, you might want to put that in the center of its own line or in a box for emphasis.
The type of sectioning I use most consistently, which is talked about in the video from Mariana’s Study Corner, is to reserve the right margin, which I use for writing down ideas I’m not immediately switching over to taking action on. For example, if there is somewhere in the code where a refactor would make the logs easier to follow, but I’d have to change a lot of code to bring it in, I might leave a note on the refactor idea in the margin. Similarly, if there is something I am concerned about, like a strange-looking log message in the code I’m experimenting with, I might write that in red on the side so later I can go back and figure out whether it was a normal log or there really is a bug. I also leave reminders there on who to talk to for understanding less-familiar code.
If you reserve the right margin for collecting ideas, I recommend using an 8.5"x11" spiral notebook so you aren’t losing as much space making that margin.
Code snippets
When I’m working on adding a new feature to existing code or debugging something, code snippets are another thing I make a section for. I box off my code snippets, often including details like which file the code’s in, as well as which functions were lower in its call stack to add additional context. Not shown in the picture below, sometimes I also use a diagonal arrow to indicate we’re switching files somewhere in the call stack.
Since code gets verbose, I use pseudocode for most of my code notes, typically in a Python or Ruby-like style even if I am coding in Go or JavaScript. I use ||= as “if this value is its zero value, change it to this default value”, and I also switch to English if that’s more readable than the actual code. And if there is code of interest being tracked, like a variable or parameter of interest, I write that in blue or underline it. Also I change this.property (or funcReceiver.property in Go) to just .property.
Just like I mentioned with abbreviations, though, there’s no one best style of pseudocode; as you develop your code notetaking, you should formulate a shorthand that is easy for you to both read and write.
Finally, to flow from the pseudocode snippet back to my ideas, I use arrows to connect the code to thoughts I write down on the code. As I mentioned before, I find it really useful to keep track of my thought process. For example, in the code snippet on the left, say I’m debugging errors we’re getting in functionYoureDebugging. I have found sendAPICall to be a possible suspect of where the error is coming from, so I keep track of my thoughts that the default value in the API call could now be causing errors.
Moving over to the right margin, I remember at standup a couple mornings ago that Lola (yep, my pupper) had made a recent fix to the service that my code is talking to, so I talk to her and sure enough, in pull request 1123 of the backend repository, the default value of her fetch function is now tennisBall, so I add a task that I need to update my calls to sendAPICall.
In general, this is more or less the core of my notetaking style; a main set of abbreviations, color coding, and sectioning my notes all make it easy to keep track of my work as it’s in progress, and help me remember my thought process when I have to review previous work. Very recently, moving one of my side projects over to Webpack 4, I found this style really helpful for coming back to that after 6 days away from doing anything with that project and Webpack.
As I mentioned above, though, everyone’s notetaking style is different, so if you’re still developing yours, I encourage you to experiment with different styles and let your technique keep evolving. If you have any questions on my style, you can find me on Twitter at @AndyHaskell2013 and on askquestions.tech, the inclusive tech Q&A forum, at canteloupeantelope. Also, I’d like to give a shoutout to Sean Kelly, Cat Turner, and Bill Kennedy for peer-reviewing this blog post. As always,
STAY SLOTHFUL!
