Forem: Huy V

The 5 free tools for taking programming notes

Huy V — Sat, 07 Oct 2023 14:49:25 +0000

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,

A short tour of ExpressJS implementation (Part 1)

Huy V — Sat, 02 Sep 2023 09:47:37 +0000

Introduction

ExpressJS is a web framework that most of us know about. I really like how easy and fast it is to set up a new server using Express.

Under the hood, Express is a lightweight wrapper around the Node HTTP module. It abstracts out some complexity of the HTTP module and provides us with a simpler way to build our backend server.

In this article, I want to understand how Express is implemented and see if I can learn something from that.

Start reading the codes

The source code of ExpressJS is available at: https://github.com/expressjs/express

First, let's check the directory structure:

├── index.js
├── lib
│   ├── application.js
│   ├── express.js
│   ├── middleware
│   │   ├── init.js
│   │   └── query.js
│   ├── request.js
│   ├── response.js
│   ├── router
│   │   ├── index.js
│   │   ├── layer.js
│   │   └── route.js
│   ├── utils.js
│   └── view.js

The main codes live in the lib folder, with a few modules such as: application, middleware, request, response, router… It is indeed simple, there are only a few files compared to other web frameworks.

Now, we can jump right into the express.js and read the codes. But I want to approach the reading process in a different way.

Let’s say that we have this tiny application that uses Express.

const express = require('express')
const myapp = express()
const port = 3000

myapp.use(whateverLogger())

myapp.use('/hello', (req, res) => {
  res.send('Hello World!')
})

myapp.post('/world', (req, res) => {
  res.send('ok')
})

myapp.listen(port, () => {
  console.log(`Example app listening on port ${port}`)
})

We can separate this application into 2 phases:

Phase 1: Registering the handlers
- In this phase, the handlers (middleware) have been set as follows: whateverLogger, and the handlers for /hello and /world.
Phase 2: Processing the requests
- This phase is where the server receives the requests and processes them

Let’s start reading the source codes following each phase.

Phase 1: Registering handlers

The main method that we need attention to are the two:

myapp = express()
myapp.use()

For the express() my first guess is to read the express.js

express.js

...
var proto = require('./application');
var Route = require('./router/route');
var Router = require('./router');
...

exports = module.exports = createApplication;

function createApplication() {
  var app = function(req, res, next) {
    app.handle(req, res, next);
  };
  mixin(app, EventEmitter.prototype, false);
  mixin(app, proto, false);
  ...

  return app
}

(omitted other details for clarity)

The function call returns an app which is also a function. The mixin(app, proto, false) indicates that most of the logic of this app will reside in the ./application

We can skip the mixin logic and assume that its purpose is to add methods and properties to the app

Our next hop is the application.js

application.js

At line 194, we can see the app.use is defined:

...
var Router = require('./router');
...

app.use = function use(fn) {
  ...
  var router = this._router;
  var fns = flatten(slice.call(arguments, offset));
  ...

  fns.forEach(function (fn) {
    if (!fn || !fn.handle || !fn.set) {
      return router.use(path, fn);
    }

    ...
  }, this);

  return this;
};

There are many activities in this method but the first thing that should catch our eyes is the fns.forEach that calls the router.use(path, fn)

app.use receives a list of functions (that are our handlers for a path). Then register each of those functions using the router.

Now let’s jump to the router.js

router.js

A lot of interesting things happen in this file.

First, the constructor codes show a stack is defined.

Whenever I see a stack (or queue), I immediately think of an array that has some sort of order when we insert or access the array.


var proto = module.exports = function(options) {
  ...
  router.stack = [];

  return router;
};

Continue, we find the definition of router.use

The sweet spot is this for loop where it creates a new Layer and pushes it to the stack

proto.use = function use(fn) {
  ...
  var callbacks = flatten(slice.call(arguments, offset));
  ...

  for (var i = 0; i < callbacks.length; i++) {
    var fn = callbacks[I];
    ...
    var layer = new Layer(path, {
      sensitive: this.caseSensitive,
      strict: false,
      end: false
    }, fn);

    layer.route = undefined;

    this.stack.push(layer);
  }

  return this;
};

Each item on the stack is a Layer
A Layer can only receive a path and a fn callback

Now at this point, I can imagine how this setup is stored in the stack:

myapp.use('/hello', handler1, handler2)
myapp.use('/world', handler3, handler4)

this will become:

router.stack = [
  Layer('/world', handler4),
  Layer('/world', handler3),
  Layer('/hello', handler2),
  Layer('/hello', handler1) // <-- index: 0
]

I believe we now have a basic understanding of how the registration process works, and what is the data structure behind the scence

Before moving on to Phase 2, here's a diagram to summarize everything.

https://www.codediagram.io/app/shares?token=5dce1a36

On Phase 2: Processing the requests, we’ll focus on how a request is processed through the middleware by looking into the implementation of the next() function

Please stay tune 😄

A short tour of ExpressJS implementation (Part 1)

Huy V — Sat, 02 Sep 2023 09:37:35 +0000

Introduction

ExpressJS is a web framework that most of us know about. I really like how easy and fast it is to set up a new server using Express.

Under the hood, Express is a lightweight wrapper around the Node HTTP module. It abstracts out some complexity of the HTTP module and provides us with a simpler way to build our backend server.

In this article, I want to understand how Express is implemented and see if I can learn something from that.

Start reading the codes

The source code of ExpressJS is available at: https://github.com/expressjs/express

First, let's check the directory structure:

├── index.js
├── lib
│   ├── application.js
│   ├── express.js
│   ├── middleware
│   │   ├── init.js
│   │   └── query.js
│   ├── request.js
│   ├── response.js
│   ├── router
│   │   ├── index.js
│   │   ├── layer.js
│   │   └── route.js
│   ├── utils.js
│   └── view.js

Now, we can jump right into the express.js and read the codes. But I want to approach the reading process in a different way.

Let’s say that we have this tiny application that uses Express.

const express = require('express')
const myapp = express()
const port = 3000

myapp.use(whateverLogger())

myapp.use('/hello', (req, res) => {
  res.send('Hello World!')
})

myapp.post('/world', (req, res) => {
  res.send('ok')
})

myapp.listen(port, () => {
  console.log(`Example app listening on port ${port}`)
})

We can separate this application into 2 phases:

Phase 1: Registering the handlers
- In this phase, the handlers (middleware) have been set as follows: whateverLogger, and the handlers for /hello and /world.
Phase 2: Processing the requests
- This phase is where the server receives the requests and processes them

Let’s start reading the source codes following each phase.

Phase 1: Registering handlers

The main method that we need attention to are the two:

myapp = express()
myapp.use()

For the express() my first guess is to read the express.js

express.js

...
var proto = require('./application');
var Route = require('./router/route');
var Router = require('./router');
...

exports = module.exports = createApplication;

function createApplication() {
  var app = function(req, res, next) {
    app.handle(req, res, next);
  };
  mixin(app, EventEmitter.prototype, false);
  mixin(app, proto, false);
  ...

  return app
}

(omitted other details for clarity)

The function call returns an app which is also a function. The mixin(app, proto, false) indicates that most of the logic of this app will reside in the ./application

We can skip the mixin logic and assume that its purpose is to add methods and properties to the app

Our next hop is the application.js

application.js

At line 194, we can see the app.use is defined:

...
var Router = require('./router');
...

app.use = function use(fn) {
  ...
  var router = this._router;
  var fns = flatten(slice.call(arguments, offset));
  ...

  fns.forEach(function (fn) {
    if (!fn || !fn.handle || !fn.set) {
      return router.use(path, fn);
    }

    ...
  }, this);

  return this;
};

There are many activities in this method but the first thing that should catch our eyes is the fns.forEach that calls the router.use(path, fn)

app.use receives a list of functions (that are our handlers for a path). Then register each of those functions using the router.

Now let’s jump to the router.js

router.js

A lot of interesting things happen in this file.

First, the constructor codes show a stack is defined.

Whenever I see a stack (or queue), I immediately think of an array that has some sort of order when we insert or access the array.


var proto = module.exports = function(options) {
  ...
  router.stack = [];

  return router;
};

Continue, we find the definition of router.use

The sweet spot is this for loop where it creates a new Layer and pushes it to the stack

proto.use = function use(fn) {
  ...
  var callbacks = flatten(slice.call(arguments, offset));
  ...

  for (var i = 0; i < callbacks.length; i++) {
    var fn = callbacks[I];
    ...
    var layer = new Layer(path, {
      sensitive: this.caseSensitive,
      strict: false,
      end: false
    }, fn);

    layer.route = undefined;

    this.stack.push(layer);
  }

  return this;
};

Each item on the stack is a Layer
A Layer can only receive a path and a fn callback

Now at this point, I can imagine how this setup is stored in the stack:

myapp.use('/hello', handler1, handler2)
myapp.use('/world', handler3, handler4)

this will become:

router.stack = [
  Layer('/world', handler4),
  Layer('/world', handler3),
  Layer('/hello', handler2),
  Layer('/hello', handler1) // <-- index: 0
]

I believe we now have a basic understanding of how the registration process works, and what is the data structure behind the scence

Before moving on to Phase 2, here's a diagram to summarize everything.

https://www.codediagram.io/app/shares?token=5dce1a36

On Phase 2: Processing the requests, we’ll focus on how a request is processed through the middleware by looking into the implementation of the next() function

Please stay tune 😄

How I host everything for my SaaS side-project on a $6 server

Huy V — Fri, 01 Sep 2023 15:30:37 +0000

Building side projects, attracting users, and earning some extra income are something I love to do after work.

Background

Since I’m a web developer, many of my ideas have these 4 standard components:

A marketing website or a landing page
A static front-end web app
An API server
A database

Being able to ship fast is my ultimate goal to validate the ideas.

The Problems

My initial idea was to use services that could automate the infrastructure and deployment for me. I tried using:

Static web hosting (Surge.sh, Firebase) for the landing page and web app
Google App Engine/Heroku Dyno for the backend and database

These tools appealed to me because I could simply type a command on my local machine and everything would get deployed.

Well, it did work that way, but when I added more requirements, I often found myself struggling through complex documentation without a clear sense of how they worked.

For example:

Why couldn't my Node app connect to the database?
How could I avoid caching the index.html file on the browser (and only cache assets)?
How could I point my Cloudflare DNS to the Node app IP?

Don't get me wrong, these tools are capable of fulfilling my requirements, but with limited time outside of work, I don't want to spend most of my time reading documentation.

The 1-server with Nginx solution

My idea is, can I install everything on a virtual machine (similar to my laptop), and use Nginx to redirect traffic?

Turns out it’s pretty simpler than I thought.

Here’s the URL mapping of my project:

www.codediagram.io/app/ is a static web app, which is a VueJS client-side app. All the assets are served from /opt/front-end-app
www.codediagram.io/ is the landing page. This is generated HTML that is optimized for the SEO. All the assets are served from /opt/landing-page
api.codediagram.io is routed to the back-end NodeJS app runs on port 5003

The reason that the static front-end app and the landing page have the same subdomain, only separated by subpath, is that these URLs are user-facing, and I want them to be consistent, easy to use, and remember.

This is the Nginx config that does all the work:

server {
    server_name www.codediagram.io;

    location / {
        root /opt/landing-page;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    location /app {
        root /opt/front-end-app;
        try_files $uri $uri/ =404;
    }
}

server {
    server_name api.codediagram.io;

    location / {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Host $host;
        proxy_pass http://localhost:5003;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_cache_bypass $http_upgrade;
    }
}

The first server block is for the landing page and the front-end app.
The second server block is for the Node instance.

To enable SSL, I highly recommend using Certbot and letting it auto-configure your Nginx config.

And that's it, everything is set!

The half-automated deployment

For the landing page and the front-end app. I wrote a small command to build and copy the build to the server.

pnpm build \
  ssh server 'rm -rf /opt/front-end-app' \
  scp -r ./.output/public server:/opt/front-end-app

For the back-end, I manually:

SSH into the server
Checkout new codes
Restarts PM2 instances

The server specs

I’m using Digital Ocean, the 6-dollar droplet is a 1GB RAM, 1vCPU. This is more than I need for now since not many people are using my product.

You can pick any cloud vendor that you like.

What I’ve learned

Setting up this environment is similar to setting up a local development on my laptop, with the exception of Nginx.
Although the Nginx configuration may seem complex at first, all routing logic is contained in that file, making it easier to understand what will happen.
Having only one server for everything streamlines many processes.
I can easily replicate this setup for any side project.

This setup is suitable for my use case, which involves a side project with low usage. However, if your project has high usage, then this is not an ideal setup.

In such cases, it is recommended to split the components into separate servers with backup and high availability features.

If you're interested, this is the tool that I built: https://www.codediagram.io/

Cheers