The 5 free tools for taking programming notes

Introduction

Programming is mentally demanding, and effective note-taking is key for software engineers.

Good notes aid in writing better code, organizing thoughts, creating abstractions, and documenting work progress.

In this article, we'll explore four free tools that significantly enhance the note-taking experience for programmers.

The 2 approaches for taking programming notes

Before we delve into comparing the tools, let's clarify what we mean by "taking programming notes."
To keep things simple, I'll categorize the use cases into two groups:

Taking notes outside coding session

This often happens when we need to do some research beforehand, give comparison for technical approaches, or write documentation for others to understand/maintain the code

Most note-taking tools available today can be used for this purpose. However, since we're dealing with code, having a "code block" feature is essential in these tools.

For example:

function foo() {
  console.log('bar')
}

Taking notes while coding

When we're adding new features to our code, it's common to have to read through existing code written by someone else. This helps us understand what the existing code does and where our new code should go.

Sometimes, the code can be very complex and spread out across multiple files, making it difficult to remember the flow of the code in our minds.

That's when it becomes helpful to have a scratchpad where we can quickly write down the main ideas about the code and create a high-level understanding of it.

Although there aren't many tools on the Internet specifically designed for this purpose, we'll soon explore a few of them.

Let’s explore the 1st category

---

1. Markdown and VSCode

This is a straightforward and accessible tool for taking notes. Don't underestimate its simplicity—VSCode is a powerful and fast editor with many customization options. It allows you to write and view Markdown files simultaneously.

Some benefits you may like with this setup:

• You can enhance your Markdown writing experience by installing various extensions, such as the following:
  • https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one
• You can choose any color theme you prefer.
• The code block formatting is handled by VSCode, ensuring good readability
• Searching and finding content within your notes is quick and effortless.
• One standout feature of this setup is the ability to open two workspaces simultaneously inside VSCode.
  • You can create a separate workspace for your notes and include it in the workspace that contains your coding repository.
  • This way, you can easily open Markdown files and copy code from your repository without any hassle.
  • https://code.visualstudio.com/docs/editor/workspaces

2. Notion

https://www.notion.so/

Nowadays, Notion is very popular, so you might already be familiar with it.

It is a comprehensive note-taking application that offers features that surpass the combination of VSCode and Markdown.

Notion is a cloud-based tool, so sharing and collaborating is well supported

Notion's code block supports numerous programming languages.

3. Obsidian

https://obsidian.md/

Obsidian is a really interesting tool. I would describe it as a note-taking app that resembles an offline version of Notion, but with the ability to install many plugins (similar to VSCode extensions).

The code block in Obsidian is awesome just like Notion

Recently, Obsidian introduced the canvas feature, which is ideal for drawing code architectures.

Obsidian is an offline application with its own advantages and disadvantages. The search function on Obsidian is extremely fast compared to Notion. However, when it comes to sharing and collaborating, Notion is far superior to Obsidian.

Chance that you already use a note-taking app like Notion and Obsidian, so unless the tool doesn’t support code block, then you can use any note-taking tool for organizing your programming notes

---

Let’s explore the 2nd category: Taking notes while coding

4. Code Annotation

https://marketplace.visualstudio.com/items?itemName=tkcandrade.code-annotation&ssr=false#review-details

The first tool in the list is this small but useful VSCode extension

Here's what it does:

• While coding, you can use the "Code Annotation: Add Note" command to add notes
• The extension stores your notes with the path to the original file
• Later, you can view all your notes in a Markdown file.

This tool is useful if you don't want to clutter your code with inline "TODO: ..." comments.

It also allows you to have a better summary of all your notes at the end of the day.

Alternatively, you can simply create a Markdown file to store your notes, although it's slightly less convenient compared to using Code Annotation.

5. Code Diagram

https://www.codediagram.io/
https://marketplace.visualstudio.com/items?itemName=CodeDiagram.codediagram

Disclaimer: this is my extension

Code Diagram is a visual note-taking tool that is integrated within VSCode.

Instead of using text-based notes, it prefers a visualization-based approach

Here's how it works:

• It offers a canvas tab where you can add your code blocks and connect them.
• To create a note, just select the code and click on "Snip it."
• This action creates a new box that contains your selected code.
• The box also includes a link to the original code file, so you can open it with a single click.

A key value of Code Diagram is to facilitate the visualization of complex code flows.

For instance, when tracing a feature that spans multiple files and includes conditional branches, rather than relying on mental tracking, you can dump the code flow into the diagram for improved visualization.

Summary

We discussed two use cases for programming notes. The choice of the appropriate tool depends on your needs. You can freely combine and use these tools together to create your optimal setup.

In the end, what matters most is finding a note-taking workflow that suits your preferences and enhances your productivity.

Cheers,