How I Approach Notetaking as a Developer

Recently, I realized the importance of—good—notetaking.

Shannon Crabill

@shannon_crabill

Don't you hate it when you refer to your notes about a project/process and it turns out you took really bad notes?

15:12 PM - 09 Jul 2019

I’ll admit that I’ve done this more than once.

My attitude toward note-taking used to be “If I don’t remember it, it must not be that important”.

Yikes.

This may have worked in an art college, were sketches and concepts were common. But, as I’ve moved deeper into the software engineer side of the track, remembering specific processes gets a lot harder.

For one, it’s not just the concept that needs to be recalled. But how.

Are you using Ruby or Javascript? The concept to get a random item from an array may be the same in both languages, but the syntax will be different. What about the output, what format should it be in? Or, does this need to account for an argument?

These are some of the things that come to mind when writing code that is similar to something that I’ve done before, but I can’t remember how I got there.

If I could dump the memory space in my brain currently occupied by every song lyric in Hercules, maybe I could remember all of the things, but for now, I’ll stick to taking better notes.

Here’s what worked for me.

Literally, Write Comments in Your Code

I’m probably not the only developer in the world that assumes future you will remember what your code does. This may be true in the short term, but long term (days, weeks, hours, etc) is a different story.

To combat this, I literally explain to myself, in the comments, what each line of code is doing.

Here’s an example using a method that randomly generates a new hex color each time it is run.

def createColor
# Lists all possible integers that can be use in a valid hex code
  hexadecimalIntegers = ["0","1","2","3","4","5","6","7","8","9","a","b","c","d","e","f"] 

# Randomly get 6 items from the hexadecimalIntegers array, then join them together at each character
color = hexadecimalIntegers.sample(6).join("")

# Puts hex color
  "Your new hex color is ##{color}" 
end

When writing comments, I like to think about how I would explain my code to someone else. I could go a step further and add a note explaining why I used .sample in place of .rand.

Write Notes by Hand

I will admit, I’ve debated if this is the route I wanted to go myself. I keep a bullet journal for to-dos but writing code by hand seemed silly when it’s so easy to copy and paste from one digital document to another.

There are studies that support pen and paper note-taking over typing, so I decided to give it a try.

My head was spinning when it came to classes in Ruby. It was a new concept with a lot of moving parts. I wanted to make sure I understood the core concepts before I moved onto the advanced parts.

When going back to review classes in Ruby, I reread the course material and took pen and paper notes. Any key concepts that I find myself forgetting—I’m looking at you instance variables—I would write it down. Similar to my inline comments, next to the code snippet, I would include in plain English what the function does in relation to the bigger picture.

Taking notes by hand, forced me to keep my notes concise and focused. Notes like this, paired with my inline notes, were helpful when comes to refactoring, which brings me to my next point.

Review and Refactor Often

Do you ever solve a problem, then feel like you don’t know what you actually did?

Perhaps it’s a side effect of wanting to learn a lot in a small amount of time. But, I’ve realized that I am better off taking the time to review the code, notes, and comments I wrote previously before moving onto new concepts.

This is where refactoring comes in.

Refactoring is a new concept to me, but I see it as improving the existing code while maintaining it’s functionality.

Usually, my inline comments present enough of a story that I know what problem the code was meant to solve, to begin with.

Then I can refer to my handwritten notes—which cover the broader concepts—to see where I can make improvements.

For example, are there variable names that I can clarify? Is there any redundant code that I can remove? Are there edge cases that my code should account for?

In closing, making an effort to write good notes can be a game-changer in your learning journey.

While written notes, supplemented by inline code comments works for me, it is important to use whatever note-taking format—written, typed, audio—works best for you.

What note-taking approach do you take when learning a new concept?

Photo by Kelly Sikkema on Unsplash

Originally published on my blog: https://shannoncrabill.com/blog/taking-notes-as-a-developer/