How I Approach Notetaking as a Developer

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

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/

Comments

[Dave Jacoby]

I have several thoughts that don't have a coherent through-line, so I'll proceed and hope coherence comes.

One of the concepts in David Allen's Getting Things Done is using external memory. In fact, that's the only part that stuck, and I'm eternally grateful. I've found that taking notes by hand helps them "stick", which I credit to years of pre-computer education, but follows your NPR link.

Regarding code comments, I'm torn. Jeff Atwood suggests writing better code instead of comments, and I'm not 100% on board, I lean toward the "why" while leaving the "how" to code. I might do something more like this:

# writes a random color in hexidecimal RGB format to STDOUT
def createColor
  hexadecimalIntegers = ["0","1","2","3","4","5","6","7","8","9","a","b","c","d","e","f"] 
  color = hexadecimalIntegers.sample(6).join("")
  "Your new hex color is ##{color}" 
end

Also, I didn't know about array.sample() but quite like it. I'm going to have to implement it in languages I use. rand, in the languages I know, would involve aligning output to array size, casting as integer and making the index, so using sample is the clear choice, once you know it exists.

But I agree on note taking and "whatever works for you". Thank you for writing this.

[Shannon Crabill]

You make a good point about separating the why and how with the comments and code. Your example is a lot cleaner and seems like it would be appropriate for more complex applications.

I've heard references to Getting Things Done (I go by the 2 minute rule when I can).

Thanks for sharing!

[Scott Simontis]

I would encourage you to check out a movement called literate programming, originally invented in the late 70s by Donald Knuth. It never really took off the way he envisioned it, and the meaning of the idea has been diluted down to systems which can scrape comments from source files nowadays.

Literate programming is about having snippets of code, or entire programs, that you can evaluate, study and modify, surround by text. It feels like a lab journal; I use it a lot when trying to figure out how to do Systems Administration tasks so when I need the script again in 6 months I will actually have it!

Not sure how familiar you are with Emacs, or if you even want to be, but Org Mode in Emacs features a literate programming library called Babel which lets you embed code blocks. The learning curve is very sharp, the community can be very grumpy if you ask a question they feel is obvious, but overall a cool experience. It does not play well with Windows, however. When it started breaking and I was spending more time fixing Emacs than I was studying, I gave it up.

One of these days it's a system I would love to build.

[Shannon Crabill]

I've heard of literate programming! It's a facinating concept (along with Donald Knuth in general)

It was referenced in an unconference session at Write the Docs and I almost referenced it in this post but it slipped by mind during editing.