evaristo.c - freeCodeCamp.org

How to Become an Analytical Programmer – Solve the "Rock, Paper, Scissors" Game 5 Ways Using JavaScript & Mermaid.js

evaristo.c — Mon, 12 May 2025 14:06:25 +0000

Over the past year, I’ve explored tools and practices that help developers build an analytical mindset. One recurring theme is how experienced programmers often describe understanding code as forming a mental picture – a conceptual map of the program’s flow.

When it comes to software development, finding ways to visualize these mental models is a common thread. Many developers describe sketching workflows or imagining them mentally to reason through code. And in my own experience working with senior developers and software architects, this visualization habit is extremely common.

A 2013 Quora post captures this well:

“A top coder sees a program graphically (…) A data structure as a hierarchy of relationships, a program as a network of data pipes… The first and only time he reduces pictures to words is when he writes code.” —Rober Wagner

So it appears that developing our ability to recognize patterns in code could help us to develop our expertise. But programming is rarely that straightforward – there are often multiple ways to solve the same problem. It also reflects a developer’s personal habits, experiences, and styles. So which patterns matter, then?

Imagine you assign the same task to five developers: build a small game using HTML, CSS, and JavaScript. Each solution should follow the same functional rules. What are the chances their code will look the same?

You’d expect that their implementations might differ, but the underlying mental workflow – the internal logic they follow – might be remarkably similar. If you can reconstruct this mental flow from each codebase, you can create a shared referential point for comparison. Once this conceptual diagram is in place, you can “overlay” it on each codebase to identify where they diverge in structure, logic, or abstraction.

Ever since I started coding, spotting “patterns” while comparing other people’s code has fascinated me. I’ve found the process of comparing code not only educational but also enjoyable.

Up until now, I’ve approached it mostly by intuition – but I’ve always felt the need for a more structured method. This article explores a more systematic approach to code comparison, reflecting on what works well and what can be improved.

How to Read this Article

This article is intentionally extensive. Instead of just showing the end result, I’ll walk you through the methodology so you can recreate or adapt it for your own code comparisons.

That said, there are different ways you might approach this article, depending on your interests:

Just curious about the idea? The core argument is already laid out in the introduction. Maybe read the conclusion too, and that might be enough for your needs.
Looking to improve your portfolio? Skim through the analyses. If you're working on a game project, you’ll find comparisons of five JavaScript implementations of Rock, Paper, Scissors. These may give you practical ideas for your own code.
Interested in code analysis? Read the whole thing. This article goes deeper into why analyzing code is valuable and presents a practical methodology – including tools – you can apply.

Here’s what we’ll cover:

Visual Tools for Code Comparison: In this part, we’ll talk about diagrams and focus on the one we’ll use for this project – the use case-driven system block diagram.
What we are going to do: here, we reveal the focus of our analysis, what we expect to do, what we will consider when making the diagrams, and a short intro to the tool we will use for this, Mermaid.js.
Five Code Examples of Rock, Paper, Scissors: Next, we’ll assess the JavaScript code of five CodePen projects, starting from the simplest one and finishing with the most complex one. At each assessment, we’ll make a comparison against the preceding projects.
Final Thoughts

Now, let’s dive in!

Visual Tools for Code Comparison

There are many tools and approaches for code analysis, and although there are more and more “automatic” ways of doing it, flow diagrams are still incredibly useful. Unfortunately, while they’re widely used in programming education and analysis, their use for comparing different implementations is rarely discussed or illustrated in tutorials.

Still, the potential is clear. Flow diagrams capture structure and logic in a compact, readable form. They're heavily used in compiler design for analyzing control flow, optimizing logic, and identifying bugs.

When applied to comparative analysis, they can highlight differences in:

Modularity and abstraction
Execution flow
Separation of concerns or unnecessary complexity

But not all diagram types are equally effective for this purpose. Traditional flowcharts often dive too deep into the nitty-gritty, repeating low-level logic like if-else branches already visible in the source. While helpful for understanding a single script, they may obscure broader design patterns when comparing multiple implementations.

When comparing codebases, a better option is to focus on code structure: how functions, modules, and scopes relate and interact. For that, system block diagrams are a better fit.

Why Use System Block Diagrams?

System block diagrams visualize a program at a higher level. They use labeled blocks to represent major components (functions, classes, modules) and arrows to show how data or control flows between them. This lets you focus on architecture: which part does what, and how do they work together?

Used for code comparison, placing two system block diagrams side by side immediately highlights structural and design differences. You can see at a glance how one solution favors modularity, another embeds logic in fewer blocks, or which one better separates concerns.

Still, system block diagrams can be drawn in different ways – some emphasizing structure, others workflow. Is there a format that combines both?

The Use Case-Driven System Block Diagram

A strong candidate is the use case-driven system block diagram. An example of this variant is suggested as part of the resources for a computer science curriculum (“Advanced Object-Oriented Programming and Design” COMP310) of Rice University.

Unlike use case diagrams (which focus only on actors and goals), use case-driven system block diagrams are more implementation-focused. They still show modules and data flow, but through the lens of system functionality and user-driven logic.

Interestingly, the example above effectively exemplifies its usage for evaluating existing architectures. This confirms the suitability of this type of diagram for comparisons between codebases. Simply draw one diagram per implementation, striving to find their same functional goal. Then, compare their workflows and structures side by side. You’ll quickly spot which solution is more modular, more efficient, or easier to maintain.

What We Are Going to Do

To elaborate upon the suitability of this methodology for code analysis, we’ll apply the fundamentals of use case-driven system block diagram methodology to analyze five JavaScript projects’ code – each created by a different developer – implementing the Rock, Paper, Scissors game on CodePen.

The Rock, Paper, Scissors (RPS) game is a simple two-player challenge where each participant simultaneously shows either a “rock”, a “paper”, or “scissors” depicted by one of their hands, usually after a countdown. Then they apply the following rule to decide the “winner”:

Rock beats scissors
Scissors beats paper
Paper beats rock

If both players choose the same option, it’s a tie.

In most programming versions, the player faces off against the computer, which makes random (or pseudo-random) choices. It’s a favorite beginner’s project because it’s easy to understand and fun to build.

The Code Examples

We are going to compare the (vanilla) JavaScript code for the following 5 projects, ordered by complexity:

“CPC Rock Paper Scissors” by Amit (@ghaste in CodePen)
“Rock Paper Scissor game using native drag & drop” by Hmz C (@HmZ2 in CodePen)
“Rock Paper Scissors“ by Brad Traversy (@bradtraversy in CodePen)
“Rock Paper Scissors OOP“ by Damian (@CvtS in CodePen)
“Recurrent Neural Network - Rock, Paper, Scissors“ by Andrew Worscerter (@amwmedia in CodePen)

In order to keep the article shorter, the full code won’t be provided here, except for some exceptional cases. You are encouraged to visit the corresponding projects in CodePen to have a look at the code alongside the analysis. Because the authors can update or even delete the code in CodePen at any time, I’ll also add links to Gists with the code I analyzed at the time I wrote the article.

Follow this link: https://gist.github.com/evaristoc/81dc9f508aa54c355f3f89b08a2450d5 if you want to find the copy of the JavaScript codes used for this article.

How to Choose Your Projects

To find the projects, I searched CodePen for any pen about “Rock Paper Scissors”. Then I checked out the edits of some of them, and chose the ones I found the most interesting. I made a point to choose ones with varying complexities.

The Scope

First of all, our goal here isn’t to judge the quality of the codebases. Instead, it’s to demonstrate how we can use this diagram-based methodology to compare them.

CodePen projects often include quick demos, experiments, or even AI-generated snippets. Some developers might be more interested in the HTML/CSS of the project. But while they don’t always follow best practices, that’s what makes this exercise interesting – the diversity of approaches reveals valuable contrasts worth analyzing.

The Methodology

For the comparison, we’re using a methodology inspired by Rice University’s COMP310 course, which suggests the following high-level steps for constructing use case-driven system block diagrams:

Add all system use cases to a single diagram. These use cases will be similar to “steps in a workflow”.
Group related cases within conceptually – or functionally – related operations.
Encapsulate groups into modules (or blocks) based on roles and responsibilities. Start drawing the relationships (note: what we should understand for encapsulation here shouldn’t be confused with other definitions like the one given in OOP).
Decouple operations as much as possible – refine scope and minimize interconnections.

In order to allow the comparison between code examples, we will try to find cases (or steps), modules, and relations that are consistently similar between each code example, independently of the “architecture”.

Although UML compliance is encouraged in the original course, we’ll take a lighter approach – preserving the intent and structure without strictly following every UML rule.

How We’ll Build the Diagrams

The Rice course focuses more on what the diagram should show, but not so much on how to actually build it. For that, I refer to a previous article where I broke down the diagram creation process. Here’s how the two approaches align:

Step (from earlier article)	Corresponds to (Rice methodology)
Define a scope	Identify the goal and context for your diagram
Find the start and end of the workflow	Identify use cases (actually, a general scanning of the workflow)
Identify deep-dive vs. generalized sections	Identify groups of cases. Prepare for modular encapsulation
Iterative refining and generalization	Applied throughout to improve module clarity and decoupling
Enhance and extend	Equivalent to fine-tuning and breaking dependencies

Feel free to revisit that article if you want a more detailed walkthrough of these steps.

Our Tool: Mermaid.js

To create the diagrams, we’ll use Mermaid.js, a JavaScript library that converts text into diagrams. It’s Markdown-compatible, which makes it especially handy for online projects, blog posts, and documentation.

The main reason I chose Mermaid.js is that diagrams are easily editable, so we can:

Focus on defining relationships instead of worrying about layout
Easily iterate and update as we discover more structure in the code
Allows code reusability

Mermaid.js is also highly configurable, allowing a certain level of customization. It was also made for the web, so it’s compatible with JavaScript, CSS and Markdown. But it’s not a perfect tool, and its use poses challenges both because of the limitations of the tool itself and even because of the limitations of using visual diagrams for code analysis.

If you aren’t familiar with using Mermaid.js, I wrote an extensive tutorial about the tool, along with its pros and cons. Although I will refrain from talking in-depth about Mermaid.js here, I will make use of some other tricks that were not included in previous articles.

Be aware that to keep consistency in sizing and titling all resulting diagrams were subjected to post-treatment, which also included color filtering to improve contrast.

Five Code Examples of Rock, Paper, Scissors

1. “CPC Rock Paper Scissors” by Amit: A project with fireworks animations

Amit is a prolific CodePen user who has been uploading about 2-3 projects per week since as early as 2021. Their most recent projects (year 2025) have increased in complexity and quality while maintaining the high productivity rate.

But in Sept 2024, Amit made a simple (JavaScript) version of the Rock, Paper, Scissors game. This code is a lightweight, user-friendly implementation with fun visual elements like result display, animations, and visual feedback for wins and losses.

Key features of this project are:

It provides a complete Rock, Paper, Scissors game with a visual spinning effect when the computer is selecting its choice.
The game has animated fireworks to celebrate wins and changes the background color to red for losses.
The game keeps the interface interactive and fun through the use of emoji, quick animations, and visual feedback for the player’s performance.

Analysis of the Project

Quickly discovering of the start and end of the workflow

The code of this pen runs immediately once it’s called. Several variables are initialized (the animationContainer, the choices, the emojiMap, and so on).

Amit also made three separate functions for each item (that is, “rock”, “paper” and “scissors”). Each of them will be added as a click event to the interface (the HTML) and they all run the same function after clicking (playGame) each with a different argument based on what the user clicked.

After the interface is cleared, some variables are initialized, and the click event is added to the different emoji. The interface will wait for click interactions from the user, which will trigger the playGame function.

Let’s make a quick diagram showing this high level of generalization:

---
title: “CPC Rock Paper Scissors” by Amit - Simple SB-Diagram
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
subgraph main
init
subgraph clickEventListener[Click Event]
    eventHandler@{shape: fr-rect, label: "event handler\n(*playGame*)"}
end
end
init --> |"(1) initialize values
clean interface
add event listeners (event handler:**playGame**)"|interface
clickEventListener --> stop@{shape: framed-circle}
start@{shape: start} --> init@{shape: hex, label: "Initial Settings"}
choices --> |"(2) user choice: either paper, rock or scissors"| clickEventListener
clickEventListener --> |"(3) animations, results"| interface
end
style start fill:black
style stop fill:black, fill-stroke:white

The `playGame` Event Handler

Let’s take a closer look at the playGame function:

  function playGame(playerChoice) {
    const computerChoice = choices[Math.floor(Math.random() * choices.length)];
    const animationDiv = document.getElementById("animation");
    const resultDiv = document.getElementById("result");

    clearInterval(animationInterval);
    let currentIndex = 0;

    animationInterval = setInterval(() => {
      animationDiv.textContent = emojiMap[choices[currentIndex]];
      currentIndex = (currentIndex + 1) % choices.length;
    }, 100);

    setTimeout(() => {
      clearInterval(animationInterval);
      animationDiv.textContent = emojiMap[computerChoice];
      displayResult(playerChoice, computerChoice);
    }, 1500);
  }

It seems that there is a lot going on only in this function that could be assumed as separated functionalities. Although not explicit, there are different sections in it:

one dedicated to calculating the computer’s choice
then a setInterval to handle an animation
then a setTimeout to clear the previous animation and run the displayResult function

The first functionality operation that’s easy to identify within the whole code, and that could be set apart, is the one in charge of displaying the results: the displayResult func.

But we need to clarify the relationships in our diagram. The displayResult function is not coming after the event handler but is called from the event handler itself. We could argue that the event handler uses the displayResult function. Let’s clarify these definitions on the diagram, and also add a legend:

---
title: “CPC Rock Paper Scissors” by Amit - SB Diagram Refinement 01
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
subgraph main
init
subgraph clickEventListener[Click Event]
    eventHandler@{shape: fr-rect, label: "event handler\n(*playGame*)"}
end
displayFunc@{shape: fr-rect, label: "display func\n(*displayResult*)"} -.-o eventHandler
end
init -.-o |"(1) initialize values
clean interface
add event listeners (event handler:**playGame**)"|interface@{shape: curv-trap, label: "interface display"}
clickEventListener --> stop@{shape: framed-circle}
start@{shape: start} --> init@{shape: hex, label: "Initial Settings"}
choices@{shape: rounded} --> |"(2) user choice: either paper, rock or scissors"| clickEventListener
clickEventListener --> |"(3) animations, results"| interface

subgraph legend
      direction LR
      start1[ ] -->|"next step"| stop1[ ]
      style start1 height:0px;
      style stop1 height:0px;
      start2[ ] -.-o|"assignation"| stop2[ ]
      style start2 height:0px;
      style stop2 height:0px; 
end

end

interface ~~~ legend

style start fill:black
style stop fill:black, fill-stroke:white

Similarly, the displayResult function uses two functions dedicated to the animations: triggerFireworks and triggerLossBackground. All the functions are declared on the main scope.

---
title: “CPC Rock Paper Scissors” by Amit - SB Diagram Refinement 02
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
subgraph main
data@{shape: lean-r, label: "constants"} --> eventHandler
init
subgraph clickEventListener[Click Event]
    eventHandler@{shape: fr-rect, label: "playGame
event handler"}
end
    displayFunc@{shape: fr-rect, label: "displayResult
display func"} -.-o |"(3) the event handler calls the display function"| eventHandler
    display01@{shape: fr-rect, label: "triggerFireworks
animation"} -.-o displayFunc
    display02@{shape: fr-rect, label: "triggerLossBackground
animation"} -.-o displayFunc
end
init -.-o |"(1) initialize values
clean interface
add event listeners (event handler:playGame)"|interface@{shape: curv-trap, label: "interface display"}
clickEventListener --> stop@{shape: framed-circle}
start@{shape: start} --> init@{shape: hex, label: "Initial Settings"}
choices@{shape: rounded} --> |"(2) user choice: either paper, rock or scissors"| clickEventListener
eventHandler --> |"(4) animations, results"| interface

subgraph legend
      direction LR
      subgraph flowlines
        start1[ ] -->|"next step"| stop1[ ]
        style start1 height:0px;
        style stop1 height:0px;
        start2[ ] -.-o|"assignation"| stop2[ ]
        style start2 height:0px;
        style stop2 height:0px;
      end
      subgraph shapes
      variable["variable"]
      style variable width:135px, fill:none, stroke:none, color:#f1ce32
      subprocess[subprocess]
      end
end
end
interface ~~~ legend

style start fill:black
style stop fill:black, fill-stroke:white

Imperative Programming

This code is very much imperative. Here’s a definition of imperative programming from Wikipedia:

Imperative programming focuses on describing how a program operates step by step (generally order of the steps being determined in source code by the placement of statements one below the other), rather than on high-level descriptions of its expected results

Finding that the project follows an imperative paradigm is helpful as it provides some general idea of what we can expect in terms of how the code is organized and the type of logic we might use. We can expect that the computation logic will follow a certain workflow.

Finalizing the diagram

Now that we have uncovered the most explicit modules and their relationships, we can work on identifying sections of the code that might be considered separated functional/operational units. These separate units can be defined as “use cases” and will become the steps of the workflow.

As a way of enhancing the diagram, I have differentiated between steps and process blocks to prevent confusion between “modules” and “cases”.

---
title: “CPC Rock Paper Scissors” by Amit - Final SB Diagram
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
choices ~~~ stop
subgraph main
init
data@{shape: lean-r, label: "constants"} --> eventHandler
subgraph clickEventListener[Click Event]
    subgraph eventHandler["playGame
event handler"]
       subgraph step03[step03 - result handling and presentation]
        delay01
        delay02
        delay01 ~~~ nonode01[ ]
        style nonode01 fill:none,stroke:none;
       end
       step01@{label: "step01 - compute computer choice"} --> step02@{label: "step02 - prepare display"}
       step02 --> delay01@{shape: delay, label: setInterval}
       delay01 --> delay02@{shape: delay, label: setTimeout}
    end
end
    subgraph displayFunc["displayResult
display func"]
       step04@{label: "step01 - compute winner"} --> step05@{label: "step02 - show results"}
    end
    displayFunc -.-o |"(3) the event handler calls the display function"| delay02
    display01@{shape: fr-rect, label: "triggerFireworks
animation"} -.-o step05
    display02@{shape: fr-rect, label: "triggerLossBackground
animation"} -.-o step05
end
init -.-o |"(1) initialize values
clean interface
add event listeners (event handler:playGame)"|interface@{shape: curv-trap, label: "interface display"}
clickEventListener --> stop@{shape: framed-circle}
start@{shape: start} --> init@{shape: hex, label: "Initial Settings"}
choices@{shape: rounded} --> |"(2) user choice: either paper, rock or scissors"| clickEventListener
step05 --> |"(4) animations, results"| interface

subgraph legend
      direction LR
      subgraph flowlines
        start1[ ] -->|"next step"| stop1[ ]
        style start1 height:0px;
        style stop1 height:0px;
        start2[ ] -.-o|"assignation"| stop2[ ]
        style start2 height:0px;
        style stop2 height:0px;
      end
      subgraph shapes
      variable["variable"]
      style variable width:135px, fill:none, stroke:none, color:#f1ce32
      subprocess[subprocess]
      stepLegend["----step----"]
      style stepLegend fill:#474949, stroke: #CCC, color:#CCC
      end
end
end

interface ~~~ legend

style start fill:black
style stop fill:black, fill-stroke:white
classDef subProc fill:#1f2020, stroke: #CCC, color:#CCC
class eventHandler,displayFunc subProc
classDef step fill:#474949, stroke: #CCC, color:#CCC
class step01,step02,step03,step04,step05,step06 step

Let’s summarize what’s happening here:

In this project, a function acting as an event handler contains most of the project logic and it assumes full execution responsibility over some of the steps of the workflow.
Once the event handler is triggered, the choice of the user is passed to it and the same function calculates the choice of the computer.
That calculation is followed by part of the preparation of the interface, then an animation managed by an Interval – followed by a nested Timeout JavaScript method.
The Timeout method has the displayResult function as a callback function. This function will take the responsibility of the remaining steps.
It is inside the displayResult where the calculation of the winner takes place. The same function controls the rest of the display of results with different displays delegated to two other functions based on who wins the game.

2. “Rock paper scissors game using native drag & drop” by Hmz C: A project using the HTML Drag element

Hmz C has not been so active as Amit, with just 7 projects in CodePen across 10 years since 2014. The pen we are going to analyze is his very first contribution to CodePen. The project appears to be a demo of the HTML Drag and Drop API that came with HTML5 by the time of its release. The game provides a clean and interactive experience of "Rock, Paper, Scissors" using intuitive drag-and-drop gestures, visual effects, and live score updates. It focuses on user experience and interactivity.

Key features of this project are:

The drag and drop interaction, with simple but clean animations.
The scoring is central to this application. Both user and computer scores are updated and displayed in real-time.
The game provides a very clean, easy-to-understand interface without looking static.

Analysis of the Project

Quickly discovering of the start and end of the workflow

By inspecting the code, you will be able to realize that this code follows a similar general pattern as the code we previously examined:

Variables and states are initialized immediately when the project is accessed.
Similarly, an event handler is added to elements in the interface, but this time they won’t respond to click events but to drag and drop events.
That event handler is the one that starts and coordinates the workflow.
The workflow ends by showing results on the interface.

Given the similarities between this project and the previous at this level of analysis, I reused the script I created for the previous chart and modified it accordingly.

---
title: “Rock paper scissors game using native drag & drop” by Hmz C - Simple SB-Diagram
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
subgraph main
init
subgraph dropEventListener[Drop Event Listener]
    eventHandler@{shape: fr-rect, label: "anonymous func
event handler"}
end
end
init -.-o |"(1) initialize values and functions
clean interface
add event listeners (event handlers for: dragstart dragenter dragleave dragover drop)"|interface
dropEventListener --> stop@{shape: framed-circle}
start@{shape: start} --> init@{shape: hex, label: "Initial Settings"}
choices@{shape: rounded, label: dragged choice} --> |"(2) user drag a choice to an area: either paper, rock or scissors"| dropEventListener
dropEventListener --> |"(3) animations, results"| interface@{shape: curv-trap, label: "interface display"}

subgraph legend
      direction LR
      subgraph flowlines
        start1[ ] -->|"next step"| stop1[ ]
        style start1 height:0px;
        style stop1 height:0px;
        start2[ ] -.-o|"assignation"| stop2[ ]
        style start2 height:0px;
        style stop2 height:0px;
      end
      subgraph shapes
        variable["variable"]
        style variable width:135px, fill:none, stroke:none, color:#f1ce32
        subprocess[subprocess]
      end
end
end
interface ~~~ legend

style start fill:black
style stop fill:black, fill-stroke:white

IIFE

This project is the only one that uses an IIFE (Immediately Invoked Function Expression) pattern to register the drag and drop listeners. It is inside that IIFE (user) where the drop listener is also declared.

(function user() {

    for (var i = 0; i < hand.length; i++) {
        hand[i].ondragstart = dragStart;
    }

    function dragStart() {
        userChoice = this.getAttribute("data-hand");
    }

    userArea.addEventListener('dragenter', function(e) {
        e.preventDefault();
        this.style.borderColor = "red";
        user_icon.style.visibility = "hidden";
    });

    userArea.addEventListener('dragleave', function(e) {
        e.preventDefault();
        this.style.borderColor = "#dedede";
        user_icon.style.visibility = "initial";
    });

    userArea.addEventListener('dragover', function(e) {
        e.preventDefault();
    });

    userArea.addEventListener('drop', function(e) {
        e.preventDefault();
        computerChoice = cpu();
        user_icon.classList.remove("fa-spin");
        user_icon.className = "fa fa-hand-" + userChoice + "-o fa-2x fa-fw";
        computer_icon.className = "fa fa-hand-" + computerChoice + "-o fa-2x fa-fw";
        this.style.borderColor = "#dedede";
        user_icon.style.visibility = "initial";
        whowins(computerChoice, userChoice);
    });
})();

This project was completed before the release of ES6 in 2015. One of the uses of the pattern is to keep the variables and functions within the IIFE isolated from the global scope. Although the IIFE is still a valid syntax, in modern JavaScript most of the functional operations where the IIFE pattern is applicable can now be implemented with the use of special keywords, special operations, and standards.

Apart of the event handler, there are two other functions – the cpu function and the whowins function – that will take care of other aspects of the functionality. Those functions are declared in the global scope.

---
title: “Rock paper scissors game using native drag & drop” by Hmz C - SB-Diagram Refinement
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
subgraph main
init
subgraph dropEventListener[Drop Event Listener]
    eventHandler@{shape: fr-rect, label: "anonymous func
event handler"}
end
cpu@{shape: fr-rect, label: "cpu
computer choice calc"} -.-o eventHandler
whowins@{shape: fr-rect, label: "whowins
winner calc / update / display func"} -.-o eventHandler
changeColor@{shape: fr-rect, label: "changeColor
animation func"} -.-o whowins
end
init -.-o |"(1) initialize values and functions
clean interface
add event listeners (event handlers for: dragstart dragenter dragleave dragover drop)"|interface
dropEventListener --> stop@{shape: framed-circle}
start@{shape: start} --> init@{shape: hex, label: "Initial Settings"}
choices@{shape: rounded, label: dragged choice} --> |"(2) user drag a choice to an area: either paper, rock or scissors"| dropEventListener
dropEventListener --> |"(3) animations, results"| interface@{shape: curv-trap, label: "interface display"}

subgraph legend
      direction LR
      subgraph flowlines
        start1[ ] -->|"next step"| stop1[ ]
        style start1 height:0px;
        style stop1 height:0px;
        start2[ ] -.-o|"assignation"| stop2[ ]
        style start2 height:0px;
        style stop2 height:0px;
      end
      subgraph shapes
        variable["variable"]
        style variable width:135px, fill:none, stroke:none, color:#f1ce32
        subprocess[subprocess]
      end
end
end
interface ~~~ legend

style start fill:black
style stop fill:black, fill-stroke:white

Now that we have an overview of how the declared functions are related, let’s identify the functional operations they are taking care of and have a better idea of the full workflow.

Finalizing the diagram and comparison to previous project

After inspecting the code and making several iterations over the previous diagram, I came up with the following final result. Reusing parts of the script I made for the previous project helped me reduce the number of iterations.

---
title: “Rock paper scissors game using native drag & drop” by Hmz C - Final SB-Diagram
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph __
subgraph main
init
data@{shape: lean-r, label: "userScore computerScore variables"} -.-o whowins
step05 --> data
subgraph dropEventListener[Drop Event Listener]
    subgraph eventHandler["anonymous func
event handler"]
        step01@{label: "step01 - compute\ncomputer choice"} --> step02@{label: "step02 - prepare\ndisplay"}
        step02 --> step03@{label: "step03 - result handling\nand presentation"}
    end
end
cpu@{shape: fr-rect, label: "cpu
computer choice calc"} -.-o step01
subgraph whowins["whowins
winner calc / update / display func"]
    step04@{label: "step01 - calculate winner"} -->
    step05@{label: "step02 - update stored data"} -->
    step06@{label: "step03 - update interface"}
end
whowins -.-o step03
changeColor@{shape: fr-rect, label: "changeColor
animation func"} -.-o step06
end
init -.-o |"(1) initialize values and functions
clean interface
add event listeners (event handlers for: dragstart dragenter dragleave dragover drop)"|interface
dropEventListener --> stop@{shape: framed-circle}
start@{shape: start} --> init@{shape: hex, label: "Initial Settings"}
choices@{shape: rounded, label: dragged choice} --> |"(2) user drag a choice to an area: either paper, rock or scissors"| dropEventListener
step06 --> |"(3) animations, results"| interface@{shape: curv-trap, label: "interface display"}

subgraph legend
      direction LR
      subgraph flowlines
        start1[ ] -->|"next step"| stop1[ ]
        style start1 height:0px;
        style stop1 height:0px;
        start2[ ] -.-o|"assignation"| stop2[ ]
        style start2 height:0px;
        style stop2 height:0px;
      end
      subgraph shapes
      variable["variable"]
      style variable width:135px, fill:none, stroke:none, color:#f1ce32
      subprocess[subprocess]
      stepLegend["----step----"]
      style stepLegend fill:#474949, stroke: #CCC, color:#CCC
      end
end

interface ~~~ legend
end

style start fill:black
style stop fill:black, fill-stroke:white
classDef clTopr fill:#1f2020, stroke: #CCC, color:#CCC
class eventHandler,whowins clTopr
classDef step fill:#474949, stroke: #CCC, color:#CCC
class step01,step02,step03,step04,step05,step06 step

Notice the strong similarities between this project and the previous one:

The order of the steps
The imperative code structure
The event handler delegates the final steps to another function
That function (whowins) executes the calculation of the winner
That same function delegates the display of the results to a different function (changeColor)
There is a preference for using functions and variables declared in the global scope

What is different in this project is:

The event handler is declared as an anonymous callback function directly in the listener
This event handler delegates the execution of the calculation of choice of the computer to a different function, the cpu function.
There are no async functionalities in this project
Different from the previous project, this one has a slightly more advanced data handling. Data were stored in global variables (userScore, computerScore) that are updated just after the calculation of the winner.

If you started self-learning JavaScript at some point between 2015 and today (2025), you might have heard of this guy. Brad Traversy is a legend among those learning to code and has also made his own learning program.

The number of resources produced by Brad is immense. His first contribution to CodePen dates back to 2017. His activity in CodePen has declined with the time, but he has been posting valuable resources nonetheless.

In 2019 he made this Rock Paper Scissors game. This code delivers a straightforward but engaging implementation with a dynamic user interface. The integration of a randomized computer choice, score tracking, and modal result display creates an interactive and visually appealing experience for users.

Key features of this project are:

Randomized opponent choice: The computer's move is randomized each round to simulate an unpredictable opponent.
Dynamic modal display: A modal window shows round results for a polished, user-friendly experience.
Re-starting the game.
Score persistence across rounds: The scoreboard tracks scores until the game is manually reset, allowing for continuous gameplay.

Analysis of the Project

Quickly discovering of the start and end of the workflow

Inspecting this other code reveals a definitive pattern in the way the game is set. Similarly to the previous projects, in this one:

it initializes variables and states immediately after the project is accessed
it has event handlers added to the corresponding HTML elements in the interface
a function is usually associated to the event handler which is the one that coordinates the workflow – in this case the play function.
the workflow ends by showing results on the interface

Also, this project in particular involves a second event handler with a function to close a modal used to show the results. A third event handler is added to restart the game.

Again, given the similarities between this project and the previous ones at this level of analysis, I reused the script I created and modified it accordingly.

---
title: “Rock Paper Scissors” by B. Traversy - Simple SB-Diagram
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
subgraph main
init
subgraph clickEventListener[Click Event]
    eventHandler@{shape: fr-rect, label: "play
event handler"}
end
end
init --> |"(1) initialize values and functions
clean interface
add event listeners (event handlers:playGame clearModal restartGame)"|interface
clickEventListener --> stop@{shape: framed-circle}
start@{shape: start} --> init@{shape: hex, label: "Initial Settings"}
choices --> |"(2) user choice: either paper, rock or scissors"| clickEventListener
clickEventListener --> |"(3) animations, results"| interface
end
style start fill:black
style stop fill:black, fill-stroke:white

This project takes a step forward in designing an event handler, the play function. Its sole responsibility would be to delegate operations to other functions.

Three functions are called from this event handler:

getComputerChoice
getWinner
showWinner

Notice that again, all those functions are declared in the global scope – but this time, the play function is also in the same scope.

---
title: “Rock Paper Scissors” by B. Traversy - SB-Diagram Refinement
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
subgraph main
getComp@{shape: fr-rect, label: "getComputerChoice
computer choice func"} -.-o eventHandler
getWinner@{shape: fr-rect, label: "getWinner
winner calc func"} -.-o eventHandler
displayFunc@{shape: fr-rect, label: "showWinner
display func"} -.-o eventHandler
init
subgraph clickEventListener[Click Event]
    eventHandler@{shape: fr-rect, label: "play
event handler"}
end
end
init -.-o |"(1) initialize values and functions
clean interface
add event listeners (event handlers:playGame clearModal restartGame)"|interface@{shape: curv-trap, label: "interface display"}
clickEventListener --> stop@{shape: framed-circle}
start@{shape: start} --> init@{shape: hex, label: "Initial Settings"}
choicess@{shape: rounded} --> |"(2) user choice: either paper, rock or scissors"| clickEventListener
clickEventListener --> |"(3) animations, results"| interface

subgraph legend
      direction LR
      subgraph flowlines
        start1[ ] -->|"next step"| stop1[ ]
        style start1 height:0px;
        style stop1 height:0px;
        start2[ ] -.-o|"assignation"| stop2[ ]
        style start2 height:0px;
        style stop2 height:0px;
      end
      subgraph shapes
      subprocess[subprocess]
      end
end
end
interface ~~~ legend

style start fill:black
style stop fill:black, fill-stroke:white

The `play` event handler as a Controller

In this project, the play function resembles more the idea of a controller. The tasks of this event handler are reduced to act as a delegator, something that we have not seen fully implemented in the previous projects.

// Play game
function play(e) {
  restart.style.display = 'inline-block';
  const playerChoice = e.target.id;
  const computerChoice = getComputerChoice();
  const winner = getWinner(playerChoice, computerChoice);
  showWinner(winner, computerChoice);
}

The Controller Pattern is a common architectural pattern used in interactive applications to manage user input by directing it to other components for processing and coordination. The play controller will be the one coordinating the actions once the user calls the function from the interface.

Modularity and Separatation of Concerns (SoC)

However, this one is very modular, following a structured procedural flow.

That modularity could be associated to achieving a better Separation of Concerns, or SoC. SoC involves designing code so each section of the code is handled by a different operational unit. Despite its size, this code shows attention to that principle in the form of functions.

Procedural Programming

Procedural programming is a form of imperative programming where procedures are delegated to functions. The way the project is designed is more in accordance to those practices.

Finalizing the diagram and comparison to previous projects

The functional operations of the functions called by the controller are more evident from the final diagram for this project:

---
title: “Rock Paper Scissors” by B. Traversy - Final SB-Diagram
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
subgraph main
init
data@{shape: lean-r, label: "scoreboard object"} -.-o displayFunc
step05 --> data
subgraph clickEventListener[Click Event]
    subgraph eventHandler["play
event handler"]
        step01@{label: "step01 - prepare display"} --> step02@{label: "step02 - compute\ncomputer choice"}
        step02 --> step03@{label: "step03 - compute winner"} --> step04@{label: "step04 - result handling and presentation"}
    end
end
getComp@{shape: fr-rect, label: "getComputerChoice
computer choice func"} -.-o step02
getWinner@{shape: fr-rect, label: "getWinner
winner calc func"} -.-o step03
subgraph displayFunc["showWinner
display func"]
    step05@{label: "stpp01 - update stored data"} --> step06@{label: "step02 - show results\nin a modal"}
end
displayFunc -.-o step04
end
init -.-o |"(1) initialize values and functions
clean interface
add event listeners (event handlers:playGame clearModal restartGame)"|interface@{shape: curv-trap, label: "interface display"}
clickEventListener --> stop@{shape: framed-circle}
start@{shape: start} --> init@{shape: hex, label: "Initial Settings"}
choices@{shape: rounded} --> |"(2) user choice: either paper, rock or scissors"| clickEventListener
step06 --> |"(3) animations, results"| interface
restartGame@{shape: rounded} --> |"(4a) restart data"| data
restartGame --> |"(4b) clean interface"| interface

subgraph legend
      direction LR
      subgraph flowlines
        start1[ ] -->|"next step"| stop1[ ]
        style start1 height:0px;
        style stop1 height:0px;
        start2[ ] -.-o|"assignation"| stop2[ ]
        style start2 height:0px;
        style stop2 height:0px;
      end
      subgraph shapes
      variable["variable"]
      style variable width:135px, fill:none, stroke:none, color:#f1ce32
      subprocess[subprocess]
      stepLegend["----step----"]
      style stepLegend fill:#474949, stroke: #CCC, color:#CCC
      end
end
end

interface ~~~ legend

style start fill:black
style stop fill:black, fill-stroke:white
classDef subProc fill:#1f2020, stroke: #CCC, color:#CCC
class eventHandler,displayFunc subProc
classDef step fill:#474949, stroke: #CCC, color:#CCC
class step01,step02,step03,step04,step05,step06 step

Let’s point out the different steps carried out by the delegated functions:

The getComputerChoice is in charge of calculating the computer’s choice.
Results are collected by the controller and passed to another function, getWinner, which is in charge of calculating the winner.
Then the results of the getWinner function are collected by the controller and passed to the next function, showWinner.
The showWinner function has a similar design as the one made by Hmz C for his project. It will have just one less responsibility, and will take only responsibilities for data handling of a slightly more complex data type for the capture and maintance of the current score (the scoreboard object), as well as displaying results.

Despite of the differences in the way the code was designed, the order of the steps is very similar to the projects we have discussed before.

Other features different from the previous code examples are the existence of a modal for result presentation and a reset functionality. We are not discussing them as they fall outside of the scope of the analyses, which is the design of the Rock, Paper, Scissors game.

4. “Rock Paper Scissors OOP” by Damian: A project written in OOP

Damian has 3 projects on CodePen, all of them made in 2020. One of them is this game. The JavaScript code implements another variation of the "Rock, Paper, Scissors" game but with a more object-oriented approach using classes to manage the game logic, player choices, and statistics.

This is a well-organized, object-oriented version of the "Rock, Paper, Scissors" game with a clean separation of concerns (result calculation, player/computer choice, and game statistics). The use of animations and UI interactions enhances the user experience.

Key features of this project are:

Object-oriented design: The code is structured into classes, making it modular, reusable, and easier to maintain.
Interactive UI: It dynamically updates the player’s and computer’s choices using visual cues (CSS classes) and shows animations for draws.
Statistics: The game tracks and updates the number of wins, draws, and losses, which are displayed in real-time.

Analysis of the Project

Quickly discovering the start and end of the workflow

This code seems more complex than what we’ve previously examined. But a closer look suggests certain resemblance to the previous ones, at least at a high level of generalization:

Again, variables and states are initialized once the project is accessed.
One of the variables that’s initialized when the project is accessed is an instance of a class, the Game class. The instance is called newGame.

---
title: “Rock Paper Scissors OOP” by Damian - Simple SB-Diagram 01
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
subgraph main
    gameInst@{shape: fr-rect, label: "Game instance"}
end
gameInst -.-o |"(1) instantiate classes, values, and functions
clean interface
add event listeners (events: startGame method bound to this)"|interface
gameInst --> stop@{shape: framed-circle}
start@{shape: start} --> gameInst
choices@{shape: rounded} --> |"(2) user choice: either paper, rock or scissors"| gameInst
gameInst --> |"(3) animations, results"| interface@{shape: curv-trap, label: "interface display"}

subgraph legend
      direction LR
      subgraph flowlines
        start1[ ] -->|"next step"| stop1[ ]
        style start1 height:0px;
        style stop1 height:0px;
        start2[ ] -.-o|"assignation"| stop2[ ]
        style start2 height:0px;
        style stop2 height:0px;
      end
      subgraph shapes
      instance[-instance-]
      style instance stroke:violet, stroke-width: 3px;
      end
end
end
interface ~~~ legend

style start fill:black
style stop fill:black, fill-stroke:white
classDef inst fill:#1f2020, color:#87f134, stroke:violet, stroke-width: 3px
class gameInst inst

Again, we can see aspects of this workflow that coincide with what we found in the previous projects – but this time those similarities are more difficult to capture. As in the previous code, the controller pattern is prevalent in this code, but instead of being associated with an anonymous function or a global one, it is now a class’s module.

The instantiation of the class runs the constructor which includes the immediate assignment of click event handlers into the interface (just as with the other projects). They use a module of the class, the startGame module, as a callback function.

The (syntactic) approach that Damian chose adds additional complexities to the code in terms of scope definition. You can spot some of the complexities by realizing the need to use the JavaScript bind method in order to keep the this context of the module function the same as the one of the instance when assigned to the event.

class Game {
  constructor() {
    this.optionsImg = document.querySelectorAll('.img');
    this.optionsBtns = document.querySelectorAll('button');

    this.optionsBtns.forEach(option => option.addEventListener('click', 
                                                                this.startGame.bind(this) //see the bind here
                                                                )
                            )

    this.youWins = document.querySelector('.results > .you-win');
    this.draw = document.querySelector('.results > .draw');
    this.PcWins = document.querySelector('.results > .pc-win');

    this.stats = new Stats(0, 0, 0);

    this.render.call(this, this.stats.getStats());
  }

In order to represent that, I used a colored link, indicating that the game instance (through the constructor) is set to be the this context of the module.

---
title: “Rock Paper Scissors OOP” by Damian - Simple SB-Diagram 02
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
subgraph main
    subgraph gameInst[Game instance]
        gameConstrt@{shape: fr-rect, label: "Game constructor"}
        startGame@{shape: fr-rect, label: "startGame
method / event handler"}
        gameConstrt -.-o startGame 
    end
end
gameConstrt -.-o |"(1) instantiate classes, values, and functions
clean interface
add event listeners (events: startGame method bound to this)"|interface
startGame --> stop@{shape: framed-circle}
start@{shape: start} --> gameInst
choices@{shape: rounded} --> |"(2) user choice: either paper, rock or scissors"| startGame
gameInst --> |"(3) animations, results"| interface@{shape: curv-trap, label: "interface display"}

subgraph legend
      direction LR
      subgraph flowlines
        start1[ ] -->|"next step"| stop1[ ]
        style start1 height:0px;
        style stop1 height:0px;
        start2[ ] -.-o|"assignation"| stop2[ ]
        style start2 height:0px;
        style stop2 height:0px;
        start3[ ] -.-o|"context of"| stop3[ ]
        linkStyle 8 stroke:yellow, stroke-width:5px
        style start3 height:0px;
        style stop3 height:0px;
      end
      subgraph shapes
      subprocess[subprocess]
      instance[-instance-]
      style instance stroke:violet, stroke-width: 3px;
      end
end
end
interface ~~~ legend

style start fill:black
style stop fill:black, fill-stroke:white
classDef subProc fill:#1f2020, stroke: #CCC, color:#CCC
class eventHandler,gameConstrt subProc
classDef inst fill:#1f2020, color:#87f134, stroke:violet, stroke-width: 3px
class gameInst inst
linkStyle 0 stroke:yellow, stroke-width: 5px

By adding the evaluation of the classes, the flow diagram gets more detailed but also more complicated.

Damian defined 4 classes for this project: Result, which was just a static method, Choice, Stats and Game:

class Result {
  static whoWin(yourChoice, PCchoice) {
    ...
  }
}

class Choice {
  constructor(yourChoice) {
    ...
  }

  getYourChoice = () => this.yourChoice;
  getPcChoice = () => this.PCchoice;

  drawPcChoice() {
    ...
  }
}

class Stats {
  constructor(wins, draws, loses) {
    ...
  }
  getStats = () => this.status;

  refreshStats(result) {
    ...
  }
}

class Game {
  constructor() {
    ...
  }

  startGame(e) {
    ...
  }

  render(stats) {
    ...
  }
}

const newGame = new Game();

The best way to keep the diagram simpler is not to detail all the steps of the functionalities. But since I’m mentioning instances, I also felt the urgency to relate those to the corresponding class. I did it using a different line type and color.

---
title: “Rock Paper Scissors OOP” by Damian - SB-Diagram Refinement
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
subgraph main
    subgraph gameInst[Game instance]
        gameConstrt@{shape: fr-rect, label: "Game constructor"}
        startGame@{shape: fr-rect, label: "startGame
method / event handler"}
        render@{shape: fr-rect, label: "render\ndisplay method"}
        gameConstrt -.-o startGame
    end
    classGame@{shape: rounded, label: "Game class"} -.- gameInst
    classStat@{shape: rounded, label: "Stat class"} -.-o gameConstrt
    classResult@{shape: rounded, label: "Result class"} -.-o startGame
    classChoice@{shape: rounded, label: "Choice class"} -.-o startGame
    classStat -.-o render
end
gameConstrt -.-o |"(1) instantiate classes, values, and functions
clean interface
add event listeners (events: startGame method bound to this)"|interface
gameInst --> stop@{shape: framed-circle}
start@{shape: start} --> gameInst
choices@{shape: rounded} --> |"(2) user choice: either paper, rock or scissors"| startGame
gameInst --> |"(3) animations, results"| interface@{shape: curv-trap, label: "interface display"}

subgraph legend
      direction LR
      subgraph flowlines
        start1[ ] -->|"next step"| stop1[ ]
        style start1 height:0px;
        style stop1 height:0px;
        start2[ ] -.-o|"assignation"| stop2[ ]
        style start2 height:0px;
        style stop2 height:0px;
        start3[ ] -.-o|"context of"| stop3[ ]
        linkStyle 13 stroke:yellow, stroke-width:5px
        style start3 height:0px;
        style stop3 height:0px;
        start4[ ] -.-|"instance of"| stop4[ ]
        linkStyle 14 stroke:skyblue, stroke-width:4px
        style start4 height:0px;
        style stop4 height:0px;
      end
      subgraph shapes
      subprocess[subprocess]
      instance[-instance-]
      style instance stroke:violet, stroke-width: 3px;
      stepLegend["----step----"]
      style stepLegend fill:#474949, stroke: #CCC, color:#CCC
      end
end
end
interface ~~~ legend

style start fill:black
style stop fill:black, fill-stroke:white
classDef isaclass fill:grey
class classGame,classChoice,classResult,classStat isaclass
classDef subProc fill:#1f2020, stroke: #CCC, color:#CCC
class eventHandler,gameConstrt subProc
classDef inst fill:#1f2020, color:#87f134, stroke:violet, stroke-width: 3px
class gameInst inst
linkStyle 0,5 stroke:yellow, stroke-width: 5px
linkStyle 1 stroke:skyblue, stroke-width:4px

With the diagram above, I tried to highlight some exceptional aspects of the architecture of this code. At some point, a Stats class’s instance will be context for the render method of the Game class’s instance. I added connections between classes and the workflow to indicate that the classes were used on those steps of the workflow.

OOP Encapsulation

One way to improve the SoC of your project is through encapsulation. Encapsulation is a concept usually related to OOP and it’s about keeping data and the methods that work with that data bundled in the same class.

This project shows efforts to achieve encapsulation:

The Stats instance it is the one that will store the data, and the methods are in accordance to its task:

  class Stats {
    constructor(wins, draws, loses) {
      this.status = {
        wins: wins,
        draws: draws,
        loses: loses,
      }
    }
    getStats = () => this.status;

    refreshStats(result) {
      switch (result) {
        case "win":
          this.status.wins++;
          break;
        case "draw":
          this.status.draws++;
          break;
        case "lose":
          this.status.loses++;
          break;
      }
    }
  }

The Choice instance will be dedicated to the calculation of the choices, and so it contains methods that respond to that task:

  class Choice {
    constructor(yourChoice) {
      this.yourChoice = yourChoice;
      this.PCchoice = this.drawPcChoice();
    }

    getYourChoice = () => this.yourChoice;
    getPcChoice = () => this.PCchoice;

    drawPcChoice() {
      const options = ["rock", "paper", "scissors"];

      return options[Math.floor(Math.random() * options.length)];
    }
  }

Finalizing the diagram and comparison to previous projects

For the final diagram of the project, I wanted to:

Emphasize the importance of the methods in the classes by mentioning them in their corresponding class, and
Indicate the apparent importance of the Stats instance in the workflow.

Here the final diagram of this project:

---
title: “Rock Paper Scissors OOP” by Damian - Final SB-Diagram
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
subgraph main
    subgraph gameInst[Game instance]
        subgraph gameConstrt["Game constructor"]
            init@{shape: hex, label: "Initial Settings"} --> statInst@{shape: fr-rect, label: "Stat instance"}
        end
        subgraph eventHandler["startGame
method / event handler"]
            step01[step01 - animation] --> step02[step02 - calculate computer choice]
            step02 --> step03[step03 - prepare display]
            step03 --> step04[step04 - calculate winner and update data]
            step04 --> step05[step05 - show result]
        end
        gameConstrt -.-o eventHandler
        statInst -.-o |"use calc'd winner to update status running refreshStats"| step04
        render@{shape: fr-rect, label: "render\ndisplay method"}
    end
    classGame@{shape: rounded, label: "Game class
---------------"} -.- gameInst
    classStat@{shape: rounded, label: "Stat class
-----------------------
+status (obj / data)
-----------------------
+refreshStats()
+getStats(result)"} -.- statInst
    classResult@{shape: rounded, label: "Result class
--------------------------
+whoWin(yourCh, pcCh)"} -.-o |"use Result static method to calculate winner"| step04
    classChoice@{shape: rounded, label: "Choice class
--------------------
+yourCh, pcCh
--------------------
+getYourChoice()
+getPcChoice()
+drawChoice()"} -.-o |use Choice instance to draw PC choice| step02
    statInst -.-o render
    render -.-o |"take Stat's status and show yourCh / pcCh
last score"| step05
end
gameConstrt -.-o |"(1) instantiate classes, values, and functions
clean interface
add event listeners (events: startGame method bound to this)"|interface
eventHandler --> stop@{shape: framed-circle}
start@{shape: start} --> init
choices@{shape: rounded} --> |"(2) user choice: either paper, rock or scissors"| eventHandler
eventHandler --> |"(3) animations, results"| interface@{shape: curv-trap, label: "interface display"}
subgraph legend
      direction LR
      subgraph flowlines
        start1[ ] -->|"next step"| stop1[ ]
        style start1 height:0px;
        style stop1 height:0px;
        start2[ ] -.-o|"assignation"| stop2[ ]
        style start2 height:0px;
        style stop2 height:0px;
        start3[ ] --o|"context of"| stop3[ ]
        linkStyle 20 stroke:yellow, stroke-width:5px
        style start3 height:0px;
        style stop3 height:0px;
        start4[ ] -.-|"instance of"| stop4[ ]
        linkStyle 21 stroke:skyblue, stroke-width:4px
        style start4 height:0px;
        style stop4 height:0px;
      end
      subgraph shapes
      variable["variable"]
      style variable width:135px, fill:none, stroke:none, color:#f1ce32
      subprocess[subprocess]
      instance[-instance-]
      style instance stroke:violet, stroke-width: 3px;
      stepLegend["----step----"]
      style stepLegend fill:#474949, stroke: #CCC, color:#CCC
      end
end
end
interface ~~~ legend

style start fill:black
style stop fill:black, fill-stroke:white
classDef isaclass fill:grey
class classGame,classChoice,classResult,classStat isaclass
classDef subProc fill:#1f2020, stroke: #CCC, color:#CCC
class eventHandler,gameConstrt subProc
classDef step fill:#474949, stroke: #CCC, color:#CCC
class init,step01,step02,step03,step04,step05 step
classDef inst fill:#1f2020, color:#87f134, stroke:violet, stroke-width: 3px
class statInst,gameInst inst
linkStyle 5,11 stroke:yellow, stroke-width: 5px
linkStyle 7,8 stroke:skyblue, stroke-width:4px

What makes this code similar to the previous ones is the following:

The order of the steps is very similar
A initial step is taken to set variables to initial stages and register an event handler function to the corresponding click events
This project is also imperative in its design

This project shares more similarities to the project by Brad Traversy.

The design of the event handler is closer to a controller pattern
Therefore, modularity and SoC seem to be concepts that guided the design.
The processing of the operations are organized according to procedural programming.

That’s where the similarities stop.

The initialization of the game is through the instantiation of a class:
```
  const newGame = new Game();
```
Different to all the previous projects, the event handler / controller is now a method of the instantiated class. The method is then registered as event handler of the click events right from the constructor when the class is instantiated.
Modularity occurs through calling methods of instantiated classes, instead of (globally declared) functions.
By using the OOP paradigm, this project shows a higher level of SoC by adding encapsulation.
There are special cases in this code where it was required to bind to the appropriate this context. Examples are the binding of the Game class methods.

5. “Recurrent Neural Network – Rock, Paper, Scissors” by Andrew Worcerster: A Project Implementing AI

Andrew Worcester hasn’t been a regular contributor to CodePen but has created about 50 projects since 2013. The project we are going to analyze was created in 2019, one year after the first release of brain.js.

This code implements a more advanced version of the "Rock, Paper, Scissors" game, which uses neural networks (via the brain.js library) to predict the player’s next move and even simulate emotions for the computer opponent based on its win/loss patterns.

This code creates an engaging, AI-driven version of "Rock, Paper, Scissors" with advanced features like move prediction and emotional simulation using neural networks.

Key features of this project are:

Neural Network for prediction: a model to predict the player’s next move based on their move history creates an adaptive gameplay experience, where the CPU adjusts its strategy.
Emotion simulation: another model simulating emotions based on the game results (win/loss history), and it displays appropriate emojis like 😫, 😊, and so on, next to its moves.
Interactive UI: The game uses DOM manipulation to display the player’s move, the CPU’s move, the result, and the CPU’s emotional state after each round.
Dynamic scoring: Both player and CPU scores are updated and displayed after each round.

Analysis of the Project

Quickly discovering of the start and end of the workflow

At a high level of generalization, this code follows the same pattern as the other projects, although the complexity of the functionalities has grown:

Again, variables and states are initialized once the project is accessed.
Apart from that, an event handler of the click event is assigned carrying an anonymous function as a callback function. The contoller pattern seems to reappear in this project too.

---
title: “Recurrent Neural Network – Rock, Paper, Scissors” by A. Worcerster - Simple SB-Diagram
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
subgraph main
init
subgraph clickEventListener["Click Event (forEach on options)"]
    eventHandler@{shape: fr-rect, label: "anonymous func
event handler"}
end
end
init --> |"(1) initialize values (dummies for cpuNextMove data) and functions (functions: brain.recurrent.LSTM net brain.NeuralNetwork emoNet, calcNextMove)
clean interface
add event listeners (event handlers: anoymous function)"|interface
clickEventListener --> stop@{shape: framed-circle}
start@{shape: start} --> init@{shape: hex, label: "Initial Settings"}
choices --> |"(2) user choice: either paper, rock or scissors"| clickEventListener
clickEventListener --> |"(3) animations, results"| interface
end
style start fill:black
style stop fill:black, fill-stroke:white

A key difference from previous projects is the training of the neural network operations. Some of those functionalities are initialized to a initial state even before the user clicks.

If we still keep a high level of generalization, we can see that several of the responsibilities of the workflow will be taken by functions and even operations outside the event handler.

The project has several brain.js functionalities in place. The most evident ones are:

The LSTM (Long Short Term Memory), which it is a neural network designed to capture associations and patterns that are separated in time or place - and it is the one associated with the prediction of the user’s next move.
A default feed-forward neural network of just one layer, designed to compare immediate patterns, and it is the one associated with the simulation of the emotions.

The LSTM is used by another function, calcNextMove, to provide an immediate result even before the user interacts with the click event: a value for the cpuNextMove variable.

cpuNextMove is indeed the calculation of the computer’s choice and it occurs before the user clicks, starting with a default value based on fake data.

---
title: “Recurrent Neural Network – Rock, Paper, Scissors” by A. Worcerster - SB-Diagram Refinement 01
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
subgraph main
init
constvar@{shape: lean-r, label: "constants and variables"} -.-o clickEventListener
LSTM@{shape: fr-rect, label: "net
LSTM"} -.-o calcNextMove
calcNextMove@{shape: fr-rect, label: "calcNextMove
computer choice"} --> cpuNextMove@{shape: lean-r, label: "cpuNextMove"}
NN@{shape: fr-rect, label: "emoNet
NN"} -.-o clickEventListener
cpuNextMove -.-o clickEventListener
subgraph clickEventListener["Click Event
(forEach on options)"]
    eventHandler@{shape: fr-rect, label: "anonymous func
event handler"}
end
end
init --> |"(1) initialize values (dummies for cpuNextMove data) and functions (functions: brain.recurrent.LSTM net brain.NeuralNetwork emoNet, calcNextMove)
clean interface
add event listeners (event handlers: anoymous function)"|interface
clickEventListener --> stop@{shape: framed-circle}
start@{shape: start} --> init@{shape: hex, label: "Initial Settings"}
choices --> |"(2) user choice: either paper, rock or scissors"| clickEventListener
clickEventListener --> |"(3) animations, results"| interface

subgraph legend
      direction LR
      subgraph flowlines
        start1[ ] -->|"next step"| stop1[ ]
        style start1 height:0px;
        style stop1 height:0px;
        start2[ ] -.-o|"assignation"| stop2[ ]
        style start2 height:0px;
        style stop2 height:0px;
      end
      subgraph shapes
      variable["variable"]
      style variable width:135px, fill:none, stroke:none, color:#f1ce32
      subprocess[subprocess]
      instance[-instance-]
      style instance stroke:violet, stroke-width: 3px;
      end
end
end
interface ~~~ legend

style start fill:black
style stop fill:black, fill-stroke:white
classDef inst fill:#1f2020, color:#87f134, stroke:violet, stroke-width: 3px
class NN,LSTM inst

This project has some complexities not seen in previous projects, so I will try to go through it slowly. Let’s first see another level of refinement where the steps are shown:

---
title: “Recurrent Neural Network – Rock, Paper, Scissors” by A. Worcerster - SB-Diagram Refinement 02
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
subgraph main
init
constvar@{shape: lean-r, label: "constants and variables"} -.-o clickEventListener
step05 --> data@{shape: lean-r, label: "data"}
data -.-o calcNextMove
subgraph step00["stepInit - calculate computer choice"]
    calcNextMove@{shape: fr-rect, label: "calcNextMove
computer choice"} --> cpuNextMove@{shape: lean-r, label: "cpuNextMove"}
    LSTM@{shape: fr-rect, label: "net
LSTM instance"} -.-o calcNextMove
    cpuNextMove -.-o Dout((A))
    cpuNextMove -.-o Eout((B))
end
NN@{shape: fr-rect, label: "emoNet
NN"} -.-o step03
subgraph clickEventListener["Click Event
(forEach on options)"]
    subgraph eventHandler["anonymous func
event handler"]
        step01["step01 - prepare a scoring table for that option"] --> step02["step02 - calculate winner"]
        step02 --> step03["step03 - calculate cpu emotion"]
        step03 --> step04["step04 - result handling and presentation: Winner"]
        step04 --> step05["step05 - update data"]
        step05 --> step06["step06 - recalculate winner and prepare display"]
        step06 --> step07["step07 - calc next move; result handling and presentation: Scores"]
        Din((A)) -.-o step02
        Ein((B)) -.-o step06    
    end
end
end
init --> |"(1) initialize values (dummies for cpuNextMove data) and functions (functions: brain.recurrent.LSTM net brain.NeuralNetwork emoNet, calcNextMove)
clean interface
add event listeners (event handlers: anoymous function)"|interface
clickEventListener --> stop@{shape: framed-circle}
start@{shape: start} --> init@{shape: hex, label: "Initial Settings"}
choices --> |"(2) user choice: either paper, rock or scissors"| clickEventListener
clickEventListener --> |"(3) animations, results"| interface

subgraph legend
      direction LR
      subgraph flowlines
        start1[ ] -->|"next step"| stop1[ ]
        style start1 height:0px;
        style stop1 height:0px;
        start2[ ] -.-o|"assignation"| stop2[ ]
        style start2 height:0px;
        style stop2 height:0px;
      end
      subgraph shapes
      variable["variable"]
      style variable width:135px, fill:none, stroke:none, color:#f1ce32
      subprocess[subprocess]
      instance[-instance-]
      style instance stroke:violet, stroke-width: 3px;
      end
end
end
interface ~~~ legend

style start fill:black
style stop fill:black, fill-stroke:white
classDef subProc fill:#1f2020, stroke: #CCC, color:#CCC
class eventHandler,gameConstrt subProc
classDef inst fill:#1f2020, color:#87f134, stroke:violet, stroke-width: 3px
class NN,LSTM inst
classDef step fill:#474949, stroke: #CCC, color:#CCC
class step00,step01,step02,step03,step04,step05,step06,step07 step
classDef connectorcpuNextMove fill:skyblue, color:black
class Dout,Din,Eout,Ein connectorcpuNextMove

We can see from the diagram that:

The cpuNextMove is pre-calculated, and so the calculation of the computer’s choice occurs before the user’s next click. I have referred to this step as “stepInit” to indicate that the first calculation occurs at initialization.
After the choice of the user is captured, its value and the value of cpuNextMove are eventually used to calculate the winner. The result is stored to keep the history of computer scoring.
The history of computer scoring is the input used for the calculation of the emotions using the emoNet.
The user’s choice is then used to create the next entry for data, which keeps the history of user scoring within the data in a dedicated format.
After calculating the winner and displaying the results, the project will use data to calculate the cpuNextMove before the user clicks again.

Finalizing the diagram and comparison to previous projects

We could have finished with the previous diagram as it is largerly refined, but I wanted to practice another level of refinement to reveal the role of that the data flow has in this project. This resulted in a more complex diagram that those previously shown:

---
title: “Recurrent Neural Network – Rock, Paper, Scissors” by A. Worcerster - Final SB-Diagram
config:
    theme: dark
    layout: "elk"
    flowchart:
        nodeSpacing: 50
        rankSpacing: 50
---
flowchart TD
subgraph _
subgraph main
init
constvar@{shape: lean-r, label: "constants and variables data@{shape: lean-r, label: "data"}
cpuWinLoss@{shape: lean-r, label: "cpuWinLoss"} -.-o Aout((A))
cpuWinLoss@{shape: lean-r, label: "cpuWinLoss"} -.-o Bout((B))
cpuWinLoss@{shape: lean-r, label: "cpuWinLoss"} -.-o Cout((C))
subgraph step00["stepInit - calculate computer choice"]
    calcNextMove@{shape: fr-rect, label: "calcNextMove
computer choice"} --> cpuNextMove@{shape: lean-r, label: "cpuNextMove"}
    LSTM@{shape: fr-rect, label: "net
LSTM instance"} -.-o calcNextMove
    cpuNextMove -.-o Dout((A))
    cpuNextMove -.-o Eout((B))
end
data -.-o calcNextMove
delay01 --> calcNextMove  
NN@{shape: fr-rect, label: "emoNet
NN instance"} -.-o step03
subgraph clickEventListener["Click Event
(forEach on options)"]
    subgraph eventHandler["anonymous func
event handler"]
        scoreValues@{shape: lean-r, label: "scoreValues"}
        step01["step01 - prepare a scoring table for this specific option"] --> step02["step02 - calculate winner and update of cpu history"]
        step01 -.-o scoreValues
        subgraph step03["step03 - calculate cpu emotion"]
           likely@{shape: fr-rect, label: "brain.likely
estimator func"} ~~~ nonode01[ ]
           style nonode01 height:0px;
        end

        Din((A)) -.-o step02
        scoreValues -.-o step02
        step02 --> step03
        step03 --> step04["step04 - result handling and presentation: Winner"]
        scoreValues -.-o step04
        step04 --> step05["step05 - update data"]
        step05 --> step06["step06 - recalculate of winner and prepare display"]
        subgraph step07["step07 - calc next move"]
             delay01@{shape: delay, label: outer setTimeout}
            subgraph step08["step08 - result handling and presentation: Scores"]
                delay02@{shape: delay, label: inner setTimeout}
            end
        end

        Cin((C)) -.-o delay02
        step06 --> delay01
        delay02 -.-o delay01
        Ain((A)) -.-o step02
        Bin((B)) -.-o likely
        Ein((B)) -.-o step04

    end
end
end
init --> |"(1) initialize values (dummies for cpuNextMove data) and functions (functions: brain.recurrent.LSTM net brain.NeuralNetwork emoNet, calcNextMove)
clean interface
add event listeners (event handlers: anoymous function)"|interface
eventHandler --> stop@{shape: framed-circle}
start@{shape: start} --> init@{shape: hex, label: "Initial Settings"}
choices --> |"(2) user choice: either paper, rock or scissors"| clickEventListener
clickEventListener --> |"(3) animations, results"| interface

subgraph legend
      direction LR
      subgraph flowlines
        start1[ ] -->|"next step"| stop1[ ]
        style start1 height:0px;
        style stop1 height:0px;
        start2[ ] -.-o|"assignation"| stop2[ ]
        style start2 height:0px;
        style stop2 height:0px;
      end
      subgraph shapes
      variable["variable"]
      style variable width:135px, fill:none, stroke:none, color:#f1ce32
      subprocess[subprocess]
      instance[-instance-]
      style instance stroke:violet, stroke-width: 3px;
      end
end
end
interface ~~~ legend

style start fill:black
style stop fill:black, fill-stroke:white
classDef subProc fill:#1f2020, stroke: #CCC, color:#CCC
class eventHandler,gameConstrt subProc
classDef step fill:#474949, stroke: #CCC, color:#CCC
class step00,step01,step02,step03,step04,step05,step06,step07,step08 step
classDef inst fill:#1f2020, color:#87f134, stroke:violet, stroke-width: 3px
class LSTM,NN inst
classDef connectorcpuWinLoss fill:white, color:black
class Aout,Ain,Bout,Bin,Cout,Cin connectorcpuWinLoss
classDef connectorcpuNextMove fill:skyblue, color:black
class Dout,Din,Eout,Ein connectorcpuNextMove

I think the use of the data in this project deserved additional explanation. In fact, it is not only the use of machine learning procedures that makes this project more complex – but also its associated use of more advanced data structures.

Here’s a selection of some possible values for some of the variables used to collect data at different points of the workflow:

data structures:

"cpuNextMove: " "👊"

"cpuEmotions: " // [object Array] (4)
["😟","😨","😕","🤨"]

"data: " // [object Array] (3)
[// [object Array] (4)
["✌️","👊","✋","✌️"],// [object Array] (4)
["👊","✋","✌️","✌️"],// [object Array] (4)
["✋","✌️","✌️","✋"]]

"scoreValues: " // [object Object] 
{
  "✋": 0.3,
  "✌️": 1,
  "👊": 0
}

"cpuWinLoss: " // [object Array] (5)
[0.3,0.3,0.3,1,0]

The way data is made (an array of arrays) is a requirement for the LSTM algorithm in this particular case.

Also interesting is the use of the scoreValues object.

        const scoreValues = {
            [options[myMoveIdx]]: 0.3,         // tie
            [options[(myMoveIdx + 1) % 3]]: 1, // cpu wins
            [options[(myMoveIdx + 2) % 3]]: 0  // cpu loses
        };

Notice how the user’s choice (myMoveIdx) is used to compute the different possible computer’s choices as key, with the values associated to each key being the potential result for the computer given that user’s choice. The values have the form of a “score”:

0 if the computer lost the match
0.3 if there was a tie
1 if the computer won the match

With this object, finding if the computer won, lost or drew consists in finding the value, or score, which key is equals to cpuNextMove. In other words, scoreValues is a template used to calculate the winner.

The computer’s score will be then saved in an array, cpuWindLoss:

cpuWinLoss.push(scoreValues[cpuNextMove]);

Values of the cpuWinLoss array will be eventually used to calculate the emotions. cpuEmotions is an array of emotion predictions based on the last 4 CPU scores. The predictions are obtained from a “table of emotions” that was arbitrarily suggested by the author (the emo object).

Aspects of this project that we can relate to previous ones are:

It is made using imperative programming.
The existence of a event handler with poor modularity makes it more comparable to the way the event handler was designed in the less advanced projects, where the event handler took most of the responsibilities of the operations and the variables and utilities were declared at the global scope.
At a high level of generalization, the essential steps of the game design stay the same:
- a function (calcNextMove) calculates the computer’s choice.
- another functionality (the operations around the emotion calculation) takes part in the realization of the “animation” associated with the corresponding display of the results.
- An operation to calculate the winner is also present.
- This project has also data handling logic, although much more advanced than previous projects

But how some of those steps are realized is very different in this project:

The computer’s choice is based on the user’s scoring history, not a random function.
The computer’s choice calculation occurs before the user clicks. While the calculation could have been done before user interaction in previous projects without affecting their outcomes (assuming the user wouldn’t have access to the value of the computer’s choice before playing), performing it at click time here might have caused performance issues due to its higher CPU demand compared to the simpler Math.random. Thus, performance likely influenced the design choices.
The calculation of the winner is based not on a typical conditional control flow (if-else) or even a ternary operator, but rather obtained from a search across a customized data structure.
Instead of using logic that generates feedback independently of previous results, this game uses a more advanced process that factors in both the computer’s move and recent game history to generate contextual UI feedback after each turn.
The different implementations for the operations carried out by this project required different types of data structures with different levels of complexity, so data handling was more complex.

If you were able to follow the analysis specifically for this project and want to compare it to a similar project implementing the same game, check the example provided by brain.js team. You might need to have a basic knowledge of Vue.js though.

Final Thoughts

As a developer, you will be exposed to many different lines of creative code yourself. Or how Robert C. Martin pointed it out in his book “Clean Code”:

“Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code.”

So, learning to understand other people’s code is an essential skill that every programmer should develop. And this learning only happens by studying other people’s code and trying to reveal their tricks and bugs.

That is why finding good ways to reveal patterns when comparing code is so important. And that has been the main purpose of this project.

When I started, I still wasn’t sure about what to expect from the approach. Let me share with you what I learned.

What I found limiting from this approach was:

The more complex the code, the more complex the diagram gets, making it difficult to read. And the more difficult the diagram, the more difficult is to work out a diagram with Mermaid.js. You will also have to make more definitions, add more color, use more tricks, and so on in order to seek clarity. And the more “solutions” you have to find to clarify your diagram, the higher the risk of making it less clear.
It takes time and practice. This kind of technique is not something that you learn all at once. You might find yourself making a lot of changes before getting the “right” result. If you are doing this with Mermaid.js or any other scripting tool, you will have to learn to script with them, too.
This approach is not about visualizing algorithms or syntax. I suspect that if you read the analyses of this article with no knowledge about machine learning or object-oriented programming, this analysis likely didn’t teach you how to do machine learning or OOP. To understand those projects you have to already have internalized the “patterns” on how to do either OOP or machine learning, or be in the right moment of your learning curve, in order to be able to extract something from the code.

What I found beneficial from this approach:

Something that I learned the hard way was that good programming is not only about algorithms and syntax: it is also about structure and organization. And this approach will give you a lot of information about that.
It helps you break the code apart into functional operations. You adopt a “divide and conquer” approach to studying code.
Even if you are not visualizing the algorithms, you learn algorithms. Why? Because the approach forces you to understand the code. In order to find those functional operations, you will find yourself forced to study what some sections of the code are doing. So you will have to study more code.
You learn by comparison. That is an interesting by-product: once you have found different implementations for a similar functional operation, you learn by their differences. The diagrams will then guide you to the sections of the code that are solving that specific problem you are interested in and you’ll be able to compare it within the context of a larger codebase.
The diagrams acts as mnemotechnical artifacts to remember pieces of code. You can use those diagrams to recall a piece of code that was interesting to you, and then you’ll be able to find it more easily than by having to go through the whole code again.

What I found more interesting about this approach is the numerous questions that came to my mind during and after doing the analyses:

Why did the author follow this approach?
What drove their decisions?
How could I better organize it if I worked on it?
Which techniques would I like to combine?
What should I avoid for this project?

And so on.

Another effect was the feeling that I could now easily recognize the same “template” in other projects without having to make the diagrams. It starts to be more natural.

If you feel you want to implement this approach next time you come across several codebases you want to compare, I recommend you do the following:

Don’t stick only to visuals. Combine this with other tools. This is just one part of the whole process. For example, use AI to get a textual description of the code and use the diagrams to visualize the flow.
Always go to the code as it is the “source of truth”. You (or AI, if you’re using it) might have gotten it wrong at certain points, so always check.
Better to compare code examples that are at your level or just a bit higher, and be prepared to challenge yourself by studying new concepts. For example, if you have just the fundamentals of OOP clear in your head but you haven’t started to work on it, find simple examples at your current level and a few more made in OOP that solve similar problems and compare the approaches. I ensure you that you will start finding the patterns.
Come up with questions. The analysis might reveal structures and workflows and help you get into new programming techniques, but it won’t tell you if those structures or techniques were the “right” solution. You have to investigate more from that point. Then you can compare theory with practice. And then you will come up with more questions!
Select projects that are not subject to change.
Don’t worry about how old the projects are. Syntax is not what you are looking to learn from this analysis. It is code structure, organization, and logic. The “map in the mind of the developer”.
Keep it real. If your goal is to learn to code and your time is limited, bear in mind that this kind of analyses will take extra time. It won’t result in concrete code either. It might be good planning for analyzing new codebases at a high level of generalization. But even if it’s too general, I assure you that the time you devote to it will be worthy.

How to Use the Mermaid JavaScript Library to Create Flowcharts

evaristo.c — Mon, 13 Jan 2025 14:19:11 +0000

If you’ve recently searched for an online diagramming tool, you might have noticed that most of them rely on drag-and-drop functionality. While this is helpful for people who can’t code, it can be hard to maintain. It can also be a bit difficult to manipulate, having to move all those shapes into an editor, and it’s not as intuitive when trying to arrange lines and boxes so they don’t overlap.

Luckily, there are solutions that have taken a different path. They are based on libraries that can organize the shapes and lines for you. What you have to do instead is provide a script designed specifically for that tool outlining what kind of shapes you want to see and their relationships.

In this article, we’ll talk about a popular script-based diagramming tool called Mermaid. You’ll learn how Mermaid works and how you can use it to create flowcharts. We’ll also cover how to style your flowcharts in Mermaid. By the end, you should be able to use this helpful tool to create your own flowcharts.

What is Mermaid?
Getting Started with Mermaid
How to Start Your Flowchart in Mermaid
Nodes and Shapes in Mermaid
How to Add Styling with Mermaid
Conclusion

What is Mermaid?

Mermaid is a JavaScript library that translates written declarations of entities and relationships into diagrams. It’s like coding a diagram. The instructions are also Markdown-compliant.

Mermaid is not the only tool of this kind. There are other ones, like PlantUML, that have been around longer. But scripting with Mermaid has a very gentle learning curve, and it distinguishes itself from similar tools in many ways:

As opposed to other tools like PlantUML, Mermaid is made for the web. It is Node-compatible, and the diagrams show as modified SVGs with inserted “foreign objects”. These are more compliant with HTML and CSS frameworks.
Also compared to other scripting libraries, the resulting charts are more visually appealing, as they use advanced algorithms to place the shapes and arrows.
Mermaid also makes strong use of Markdown for labelling, and has more recently started using JavaScript object-like formatting for shape declaration.
It also has a strong support, is actively maintained, and makes use of well-known, robust JS graphics libraries like d3.js, cytospace.js, and dagre-d3.

When compared to the most common drag-and-drop types of diagramming tools, Mermaid has the same advantages as other script-based diagramming tools. With a script, we can talk about version control, reusability, and many other terms associated with programming and automation that might not be possible with drag-and-drop tools.

Challenges with Mermaid

Of course, it is not a perfect tool. One of the main challenges with Mermaid – and with many script-based diagramming tools – is that it’s a WYSIWYG tool: Mermaid’s results are almost impossible to predict, and after that they are hard to customize.

Also, for each diagram you can make with Mermaid, there are prescribed shapes and arrows – the introduction of new shapes or relationships are limited.

Some other limitations are:

As with other script-based tools, the script is not easy to debug, and for large diagrams the script can get very messy.
Even if the syntax is usually very intuitive, you have to learn a different syntax for each type of diagram.
Specifically for Mermaid, if you want to post-process the resulting diagram, you must find appropriate tools that can read the modified Mermaid SVGs.

But if you use Mermaid for the cases where it performs well, you will have an excellent tool at your service.

Mermaid allows you to create about 21 types of diagrams, each with its own syntactic rules. In this tutorial, we’ll take a closer look at the flowchart syntax, which I’ve been working with recently. This guide is for those comfortable with scripting, looking to build flowcharts, and seeking a quick reference to Mermaid syntax before diving deeper into the full documentation.

To keep this content focused on Mermaid syntax, I will avoid going into details about using JavaScript in combination with Mermaid and will instead refer to the relevant Mermaid documentation where applicable.

I’ll also highlight a few minor issues I’ve noticed while using the latest version of the tool (version 11) to help you avoid potential pitfalls.

Finally, if you need more guidance on creating flowcharts in general, I’ve created a separate post that walks you through the process step-by-step. While the examples in that post use Mermaid, its use is entirely optional.

Getting Started with Mermaid

You can use Mermaid in several different ways.

For those comfortable with web technologies, you can install Mermaid as a package or plugin and integrate it into applications using the Mermaid API, CLI, or plugins.

Once installed, you can render Mermaid diagrams wherever Mermaid syntax is included in your HTML or markdown files. The official documentation provides an example of rendering diagrams using a CDN (ESM style):

<html>
  <body>
    Here is one mermaid diagram:
    <pre class="mermaid">
            graph TD
            A[Client] --> B[Load Balancer]
            B --> C[Server1]
            B --> D[Server2]
    pre>

    And here is another:
    <pre class="mermaid">
            graph TD
            A[Client] -->|tcp_123| B
            B(Load Balancer)
            B -->|tcp_456| C[Server1]
            B -->|tcp_456| D[Server2]
    pre>

    <script type="module">
      import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
      mermaid.initialize({ startOnLoad: true });
    script>
  body>
html>

If you're using GitHub, Mermaid is supported in GitHub markdown. Additionally, Zaira Hira has written a helpful guide for Visual Studio Code users. Check your IDE for available plugins and extensions.

💡

Important Note on CSS Collisions: When installing Mermaid in your project, watch for CSS naming conflicts. Mermaid (version 11) uses fixed classes and IDs to render SVGs, which may overlap with your project’s styles, causing hard-to-detect errors.

If you’re not interested in integrating Mermaid directly into your coding, online editors and cloud tools are a great option. Mermaid provides two key tools: Mermaid Chart and Mermaid Live.

Mermaid Chart is a cloud-based project manager designed for collaboration and sharing. It offers features like templates, version history, and presentation capabilities, making it ideal for project management.
Mermaid Live is best for quick, one-off diagrams. You can see a view of Mermaid Live on my computer in the image below. You can select a diagram from sample options, modify its code in the editor under the “ Code” tab, or paste your own script. Changes instantly appear in the Diagram window, and diagrams can be exported as PNG or SVG from the Actions menu.

While Live is convenient, it’s not a reliable way to track your scripts, so save your work externally. There are other online editors similar to Mermaid Live, and Zaira Hira’s article provides insights into one of them.

For the following explanations, any installation you choose will work just the same, as we are going to put emphasis on the code. So choose your tools and let’s check out some Mermaid flowchart syntax.

How to Start Your Flowchart in Mermaid

In order to create your first Mermaid diagram, you have to tell Mermaid what type of diagram you want to make. We are making a flowchart, so to start one you can just write this:

flowchart

Mermaid can distribute the shapes in two directions: top-down (default) or left-right. If you want to be specific about the layout direction, you have to write TD for top-down:

flowchart TD

and LR for left-right:

flowchart LR

Just keep in mind that you can select only one direction for your flowchart (either TD or LR).

How to Write a Comment

Now, before we start using shapes, let’s see how to write a comment in a Mermaid flowchart. A comment will not render on the chart – they’re just there to help you out. You likely know how useful they are as a developer.

To write a comment, just precede the text of the comment with “%%” :

flowchart
%% This is a comment!!!

How to Configure your Flowchart

There are (or were) at least three ways to configure your flowcharts in Mermaid. The first one, using directives, is deprecated but still works for some cases. The second one is a frontmatter config. The other one is through a configuration file.

If you were using old versions of Mermaid (<10.5.0) you could’ve configured your chart using directives. You do that by declaring a JavaScript-object-like statement enclosed between percentages (“%%…%%”) symbols, usually after declaring the diagram type, like so:

%%{init: { 'flowchart': {theme:"base", themeVariables:{primarycolor:"#00ff00"} } }%% 
flowchart
    Hello --> World

💡

By the time of this writing, the Mermaid documentation sometimes still refers to directives as a way to configure your diagram. But keep in mind that the use of directives doesn’t work correctly in some renderers.

The frontmatter configuration method has replaced the directive method since version 10.5.0. It’s based on the YAML format. In that case, you have to use a YAML block before initializing your flowchart:

---
title: Hello Title
config:
  theme: base
  themeVariables:
    primaryColor: "#00ff00"
---
flowchart
    Hello --> World

Directives and frontMatters are limited in scope compared to other configuration methods. They apply only to the graph below the configuration statement.

For developers who are installing the Mermaid package, the recommended method for configuration is using JavaScript. Mermaid is also configurable through a JSON configuration file that exists in the folder of the library. For more details about those methods, consult the documentation chapter about API usage.

You can find a list of the attributes and properties that you can affect when configuring your diagram on this page of the Mermaid documentation.

I won’t go into much detail about configuration in this article, although I might refer to it a couple of times just to clarify a couple of things that can only be done by configuring the tool.

Nodes and Shapes in Mermaid

Across the Mermaid documentation, nodes are used as a generic term to refer to any step that is added to the flowchart. Mermaid documentation then introduces the shapes, also called node shapes. They are the representations of what happens in that node.

How to Create Your First Node (The Process Shape)

Adding a node to a flowchart with Mermaid is very easy. Just think of a unique name – or its ID according to the Mermaid documentation. For the sake of clarity, I’ll also refer to this ID as the node ID.

The node ID should be a single word with no space and preferably no other characters other than alphanumeric ones. The node ID will hold for the rest of the script and you will use it to recall that shape in other parts of the script.

Then adding the node consists in simply writing down the node ID under the diagram type declaration (here it’s A):

flowchart
    A

Notice that so far we haven’t declared any shape for that node. When no shape is declared, the default shape is a rectangle, which is also the Process shape.

💡

In Mermaid flowchart syntax, there is no way to declare a node without declaring at least one shape (the process shape)

The text that appears inside the shape is its label. There are different ways to label your shape. If you don’t label the shape, the ID is used as the label.

You can be as descriptive as you want with your node ID. You can provide a more meaningful name that can also be read as a label:

flowchart
    flowChartProcess

💡

The indentation is not required when scripting with Mermaid, but I am doing it in order to keep the script organized.

As a rule, the name should be a single word, with some limitations when not using alphanumeric characters. For example, using some characters such as spaces is not allowed, like in this case: flowChart Process . Here the rendering would result in an error.

💡

There are reserved words and characters, such as the word “end” or the parenthesis “(…)”, that can’t be used as an id as they have specific uses. But you can use any reserved word as labels when labels are specified, as long as the label is enclosed between quotes.

How to Declare Shapes and Shape Labels with Mermaid: Two Different Syntaxes

In Mermaid, you declare a node with an ID. Then you define a shape for that node.

You’ll need to be aware of the two different syntaxes available when declaring shapes with Mermaid. They are both live and can coexist in the same script as long as the interpreter is updated to the last version.

Let’s see the several ways of declaring those shapes. The following are two examples of the two available syntaxes. You can see how they’re used in the following example to render similar results:

flowchart LR
    flowChartProcess01[Process shape, version 10 syntax declaration, simplest labelling]
    flowChartProcess02["Process shape, version 10 syntax declaration, double-quoted labelling"]
    flowChartProcess03@{ shape: rect, label: "Process shape, version 11 syntax declaration, simplest labelling"}

Notice that in the example above, the first declared node didn’t require any quotes. That was because there were no special characters.

💡

As soon as you need to include reserved characters or words in your label, you must use quotes.

The first two declared nodes are examples of the original syntax. Even if not completely accurate, we will refer to that kind of syntax as the version 10 syntax.

As you can see from the script above, the version 10 declaration always contains:

the name id,
followed by a combination of characters that describe the shape and that act as shape’s opening and closing characters,
with a text labelling between the shape characters.

A shape’s opening and closing characters are mostly a combination of punctuation characters. Examples of special shape enclosing / opening characters are parenthesis, brackets, curly brackets, “less than“, “greater than”, and slashes. How you combine the enclosing characters will determine the kind of shape you want. For example, in the previous case, the Process shape was declared as ID[].

💡

When declaring shapes with version 10 syntax, you always must provide a label. If you don’t do that, it will throw an error.

Starting with version 11.3, Mermaid introduced syntax updates aimed at greater flexibility. The last example of our script above is written using that new syntax.

For the version 11 declaration, you would use JavaScript-object-like syntax in this way: ID@{shape: shape-alias, label: ”This is a label”}. We will refer to that kind of syntax as the version 11 syntax. With this version, both properties are optional. If no shape is provided, it will show a rectangle instead. If you don’t add a label, then the renderer will use the node ID as a label.

The documentation provides a list of the proper names for each shape. Furthermore, you can use several aliases instead of the proper name as shape value. In this project, for the sake of simplicity we will stick to a single option for the naming with no reference to whether it is a proper name or an alias. If you want to get the full list, just consult the documentation.

💡

Either using version 10 or version 11, you have to define labels and shapes only once in your script.

In other words, if you have a node that is used in more than one relationship in your script, you will be ok defining the shape just for one of those node ID calls, as in the following example:

flowchart
    A --> B
    A --> C
    D --> A[one time is enough]
    F --> D
    %%F --> A(uncommenting this will change the shape and the label too)

But notice in that example that I’ve commented out one of the lines. If you uncomment that line, the label and shape will update to the new definitions for node A. In general, if you define different shapes or labels for the same node in different parts of the script, the last definition will take precedence.

I have found that, when using the modern declaration, you have to add a space after the colon (“:”) before the text, otherwise the interpreter won’t find the text.

This one I have found to be incorrect (no space between shape and text):

{shape:text, label:text}

And this one was correct (a space after shape:):

{shape: text, label: text}

Quick Look at the Most Typical Shapes

There are more than 40 shapes available for flowcharts, as reported by the Mermaid documentation about shapes. In the Mermaid documentation, shapes are named based on their geometry but also based on what they mean. Some of those shapes are named only based on their meanings, especially when there is not an easy word in geometry terminology that you can use to describe the shape.

💡

In case you just want a list of essential shapes to start working on your flowchart but you don’t know which ones to pick, you can check out my article about flowcharts, where I give you some ideas.

These are the most common shapes that you’ll typically use when building a flowchart:

As you can see in the table above, we have the following shapes:

A start or end point (some people represent those kind of points with ovals, but in the Mermaid documentation the start point is represented by a circle, while the end point is represented by two nested circles)
Arrow (a connector that shows relationships between shapes)
Parallelogram (an input or output)
Rectangle (a process)
Diamond (a decision)

Let’s go through each of these shapes now and see how to make them with Mermaid.

The Terminator Shape

As mentioned above, Mermaid use circles as the representation of the start point and the end point instead of the oval. The start and end points mark the starting and ending points of the process/system.

If we stick to the Mermaid documentation, the way to make them in Mermaid using version 10 and version 11 is as follows:

flowchart TD
    startv10((start v10))
    stopv10(((stop v10)))
    startv11A@{shape: circle, label: Start v11}
    startv11B@{shape: start, label: Start (small circle) v11}
    stopv11@{shape: dbl-circ, label: Stop v11}
    stopv11B@{ shape: framed-circle, label: Stop (small circle) v11 }

In Mermaid v11, there are two types of circles you can use as a start and end points: a small shape and a regular shape. The small shapes don’t render the labelling.

If you decide to use the oval as the terminal (start/end points) shape, the simple circle might acquire other meanings. For example, it might become a connector shape (one that’s the exit point of a flowchart that continues in a separate flowchart or another point of the same flowchart). Or it might become another kind of connector that brings together several flowlines into a single flowline ( not as a multiprocess join, but just one that reduces the number of links when you’re looking for clarity).

If you prefer to use the oval (which in Mermaid is called the terminal shape), you can create it with the following code:

flowchart TD
    terminalv10([Terminal point v10])
    terminalv11@{ shape: stadium, label: "Terminal point v11" }

The Arrow (Rectangle) Shape

We’ll talk more about this one later on in this article.

The Input/Output (Parallelogram) Shape

You can use the parallelogram shape as an abstraction for data that’s available for input or output or for resources used or generated. It indicates that some information is required at this point in the workflow.

You can make this shape with Mermaid using the existing versions as follows:

flowchart TD
    inputoutputv10[/Input / Output v10/]
    inputoutputv11@{ shape: in-out, label: "Input / Output v11"}

The Process (Rectangle) Shape

You can represent a process using a rectangle in a flowchart. It represent a single step in your workflow, like an expression (for example, x = y*x²), a entire block statement, like “loop through array and update values by multiplying by 2”, or an entire sub-process, like an existing function or even a module.

It’s also referred to as a box (using the two versions):

flowchart TD
    processv10[Process v10]
    processv11@{ shape: rect, label: Process v11 }

The Decision (Diamond) Shape

A decision is represented by a diamond. It’s an abstraction for a condition’s test, a YES/NO, or TRUE/FALSE question. It is the equivalent of an IF/ELSE statement in coding.

Using version 10 and version 11, you can make a diamond as follows:

flowchart TD
    decisionv10{Decision v10}
    decisionv11@{ shape: diam, label: Decision v11 }

Markdown and HTML in Mermaid

One of the most helpful features of Mermaid is that it accepts Markdown syntax for its labelling, as well as HTML. I would advise that you use Markdown notation, as HTML notation can result in silent errors.

Using double quotes and Markdown allows you to use special characters in your labels. But with Markdown syntax, you can also access various Markdown functionalities.

To use Markdown, you have to enclose your text in double quotes (“) followed by a backtick (`), like so:

flowchart TD
    flowChartProcess["`**flowChart Process**:
                        - typical shape declaration 
                        - *Markdown-style* labelling`"]

💡

Be aware that not all Markdown functionalities are recognized.

Now that you know how to use some basic shapes as well as how to use Markdown in Mermaid, let’s go on to the next step: how to draw relationships between shapes.

Edges (Relationships) and Edge Labels in Mermaid

Edges, also referred as arrows or links in Mermaid’s documentation, are the connections between nodes. They are officially called flowline shape by the ANSI standard. This is because a link might not be an arrow in some situations.

💡

I will refer to them as edges or links here, not arrows.

Drawing relationships between two nodes is as easy as adding nodes. To draw a simple arrow link between two shapes, you just have to do the following:

flowchart TD
    A --> B

Technically, a link in Mermaid is the combination of a line and a marker. The marker is the small icon added at the end of the line. There are several types of links/edges you can draw by combining the different kinds of lines and markers that Mermaid provides:

flowchart TD
    %% dotted line, triangle marker
    A -.-> B
    %% thick line, triangle marker
    C ==> D
    %% solid cross-edged (solid line, cross marker)
    E --x F
    %% solid circle-edged (solid line, circle marker)
    G --o H
    %% combining circle marker with dotted line
    I -.-o J
    %% hidden
    K ~~~ L

💡

Be aware that “o” and “x” become reserved characters when used as markers. If you need to use them as the first character of the node ID, either leave a space after the edge operator, or use capital letters.

Edges can also be bidirectional, for example:

flowchart TD
    A <--> B

When drawing edges, you can use “syntactic sugar” in your script to reduce redundancy when defining relationships between nodes. For instance, if you have a node B situated in the middle of a sequence, you can simplify your script by chaining relationships instead of repeatedly specifying connections between B and its preceding and succeeding nodes. Also, operators can indicate crossed relationships between the same nodes.

The following script illustrates the difference between a verbose syntax (shown as comments) and a simplified syntax using chaining and operators:

flowchart TD
    %% ommitting a shape in between (chaining). the same as:
    %% A --> B
    %% B --> C
    A --> B --> C

    %% use of special character. the same as:
    %% D --> F
    %% D --> J
    %% F --> K
    %% J --> K
    D --> F & J --> K

Labelling links is also possible with Mermaid syntax, and it is very easy to do. There are different ways you can label a single arrow, as explained in the comments of the script: either inserting the label in between the line operator (—), or using vertical bars (|...|) placed after the marker (or when no marker, after the line operator) and before declaring the node:

flowchart TD
    %% inserting the label between the link operator
    A --"This is a label **between the link operator**"--> B

    %% adding a link label between vertical bars, |...|
    A --> |"This is a label **between special characters**"| B

Both of those formats accept simple double-quoted or Markdown-style labelling. I have found myself more comfortable adding labels to links using the vertical bars.

💡

Edge labelling is subject to the same restrictions as shape labelling when using reserved characters and words.

Now, before going on to the next section, let’s look at a quick example using what we have learned so far! I will use the typical syntax format for the example. Here it is:

flowchart TD
    A["Process A"] --> |"Process A is followed by Process B"|B["Process B"]
    C["Process C"] -.-> |"Process C relates to Process B"| B
    D["Process D"] --> |"Process D is followed by Process C"| C

Subgraphs

In Mermaid you can also group sections of nodes under subgraphs. Here is an example right from the Mermaid documentation on how to create the syntax for a subgraph:

flowchart LR
  subgraph TOP
    direction TB
    subgraph B1
        direction RL
        i1 -->f1
    end
    subgraph B2
        direction BT
        i2 -->f2
    end
  end
  A --> TOP --> B
  B1 --> B2

Notice that in that example, we were also able to declare different flow directions for the different (sub) graphs.

But the Mermaid documentation also clarifies a caveat: if a node inside a subgraph is connected to another node outside that subgraph, any declaration of subgraph direction will be overridden by the one declared for the most external (parent) subgraph. Again, here’s an example right from the Mermaid documentation:

 flowchart LR
    subgraph subgraph1
        direction TB
        top1[top] --> bottom1[bottom]
    end
    subgraph subgraph2
        direction TB
        top2[top] --> bottom2[bottom]
    end
    outside --> subgraph1
    outside ---> top2

In the case above, the subgraph2 was declared to be a top-bottom subgraph, but inherited the direction of the external subgraph which was declared as a left-right one. That happened because of the connection between two nodes belonging to different subgraphs at different declaration layers (the subgraph2 is inside the “global” subgraph). In this case, subgraph2 is a child of the global subgraph, so it inherits is direction.

How to Add Styling with Mermaid

Styling in Mermaid is very CSS-compliant.

Let’s start with styling shapes. One way of doing it is by using the style command. It works as follows:

Use the reserved word style,
followed by the name ID of the shape you want to style,
then indicate the properties you want to change and their new values.

We’ll implement that pattern in the following example. Let’s assume that I want to differentiate between using different colors, and change the color of the letters of the labels:

flowchart TD
    A([this should be black with white letters]) --> B([this should be grey with white letters])
    style A fill: black, color: white
    style B fill:grey, color:#fff

It’s important to understand that in Mermaid, styling is read up to the node level, not the shape level. You can apply different styles for the same node, too. They are read sequentially in order of appearance, so for two competing styles, the last one will be the valid one.

You can place the style expression anywhere in your code, but I would recommend doing it at the end of the script so you can track all changes.

💡

Keep in mind that if, when styling, you refer to a non-existing node ID, Mermaid will create a new node without warning you.

Another useful way to add styling to your flowcharts, especially when you want to add the same styling to more than one node, is by defining classes. For that, you can use the special word classDef like so:

Write classDef on one line
followed by the name you have chosen for the class
followed by the styling attributes that you want to change and their new values.

To apply the class:

Find the nodes for which you want to implement the change
add three colons (:::) at the end of the node declaration, and if labeling, at the end of the labeling expression
add the name of the class.

The following is an example on how to add classes to shapes:

flowchart TD
    A[label A, no class] --> B[label B, class bar]:::bar
    B --> C[label C, class foo]:::foo
    C --> D[label D, class bar]:::bar
    C --> E[label E, class foo]:::foo
    classDef foo fill:green, color:#fff
    classDef bar fill:orange, color:#666

💡

Same as shape declaration, classes can be assigned to a node just once, no matter where in the flowchart. But you can add only one class per node.

Unfortunately, this kind of classDef is only applicable to shapes using version 10 syntax.

Something that the documentation doesn’t mention is that you can also style subgraphs. In fact, the name that you provide to a subgraph becomes its ID.

The styling formats applicable to shapes work almost the same for subgraphs. But the use of the classDef styling only works if the subgraph is also a node in the diagram.

The following example shows the application of the style command and the classDef command and how you can use them to add styling to subgraphs:

 flowchart LR
    %% applying a class as follow will give an error:
    %% "subgraph subgraph1:::asNode"
    subgraph subgraph1
        direction TB
        top1[top] --> bottom1[bottom]
    end
    subgraph subgraph2
        direction TB
        top2[top] --> bottom2[bottom]
    end
    outside:::asNode --> subgraph1:::asNode
    outside ---> top2

    style subgraph2 fill:orange
    classDef asNode fill:grey, color:orange

If you want to style edges, then you have to proceed differently. What actually worked for me was the use of another reserved word, linkStyle, which styles the line of the edge.

The problem with edges is that they don’t have IDs: they are treated more like being part of an array, so they should be referred with an index – which won’t always correspond to the edge you want. Here is an example, based on this discussion:

flowchart TD

A --> B
B --> C
B --> D
D --> E
D --> F

linkStyle default stroke:red
linkStyle 0 stroke-width:4px,stroke:green
linkStyle 3 stroke:blue
linkStyle 4 stroke:blue

The other problem with styling edges is that markers are decoupled from lines. So this method won’t affect the marker.

In general, I have found that adopting a consistent styling for edges is not simple with Mermaid. But it might be that for most of your projects, styling edges isn’t necessary.

Apart from deciding the styling of the line, the documentation suggests that we can apply some styling to the curvature of the line configuring the diagram using directives:

%%{ init: { 'flowchart': { 'curve': 'stepBefore' } } }%%
graph LR
A --> B
B --> C
B --> D
D --> E
D --> F

The change should apply to all the edges in the flowchart and it should be based on the d3-shape library. But to date I haven’t been able to reliably configure curvature using either the directive method or the frontMatter method.

Keep in mind that the utilities to style edges with Mermaid might improve in the future. Meanwhile, I suggest asking dedicated communities about how to better style links with Mermaid if this is something you would like to implement for your diagrams. Share your findings with me to complement this article!

Finally, another way we can add more styling by affecting themes, layouts, and looks, which are set pre-set styling formats that you can modify. They will affect the styling of the whole diagram.

For example, out of the Mermaid documentation about the general syntax is this script using the frontMatter method:

---
config:
  layout: elk
  look: handDrawn
  theme: dark
---
flowchart TB
  A[Start] --> B{Decision}
  B -->|Yes| C[Continue]
  B -->|No| D[Stop]

There are more ways to add styling, but they are more advanced. For the sake of simplicity, I will not discuss those more advanced solutions and will instead invite you to explore the Mermaid documentation.

Directives or frontMatter?

As I explained previously in this article, you can configure some attributes of the flowchart with either directives or YAML frontMatter. The documentation suggests that directives are deprecated.

Those methods can be used to configure the look-in-field of the whole diagram and/or some properties of the flowchart.

But I have been able to modify some properties of the flowchart with frontMatter as well as directives. For example, have a look at the following two examples, where the fill attribute is set based on a template theme, and the nodeSpacing is also modified:

---
title: Hello Chart
config:
    theme: base
    flowchart:
        nodeSpacing: 200
---
flowchart LR
A --> B
B --> C
B --> D
D --> E
D --> F

%%{init:{'theme': 'base', 'flowchart':{'nodeSpacing': 200}}}%%
graph LR
A --> B
B --> C
B --> D
D --> E
D --> F

The results of both are almost the same, although on this occasion I couldn’t add a title to the one using a directive. There must be some advantages in preferring the YAML frontMatter approach, but be aware that you can still use both for some cases.

For details about the configurable flowchart properties using these and JavaScript methods, visit the Mermaid documentation. If you want examples on how to configure themes, follow this resource. At the time of this writing, configuring through directives or frontMatter is something that I haven’t explored in depth. I invite you to give it a try and let me know what you discover.

Interactivity

Another thing that you can do with Mermaid is adding simple interactivity. You can do this by using the following pattern, using the reserved words click, call and callback, where callback is the name of a callback function:

click nodeId callback "Tooltip when hovering"
click nodeId externalLink "Tooltip when hovering"
click nodeId call callback() "Tooltip when hovering"

This kind of interactivity is applicable when you have rendered the Mermaid flowchart in HTML and you have a JavaScript file associated with it. But for simple solutions, you can also make calls to a external pages by using the following pattern, as suggested by the documentation:

flowchart LR
    A-->B
    B-->C
    C-->D
    click A callback "Tooltip for a callback"
    click B "https://www.github.com" "This is a tooltip for a link"
    click C call callback() "Tooltip for a callback"

Be aware that the configuration of the whole project, and not only the Mermaid configuration, might prevent you from using the interactive functionalities successfully. For example, the script given above cannot work from this article.

Visit the recommended resource given by the documentation itself for a working example for tooltips, but no links: https://jsfiddle.net/yk4h7qou/2/. Check the examples in the Mermaid documentation to see how links work, but the tooltips won’t work: https://mermaid.js.org/syntax/flowchart.html#interaction.

If this is something you want to try, read the documentation carefully for more insights about what you have to take in consideration when implementing this kind of solution.

Mermaid, CSS, and SVG

💡

Mermaid documentation makes no reference to how SVGs are structured. Here I have made a quick review on how SVGs are rendered in the most recent versions.

You can go further than the functionalities provided by Mermaid by acting on the SVGs that the tool produces. The resulting SVG can be styled, the shapes can be modified, and so on based on your own needs and requirements.

So far, I have found that Mermaid produces an SVG that has a higher level structure like the following:

svg -----
        |
        (group)
        |
        markers and defs
        |
        group: class root ----
                              |
                              group: clusters (subgraphs)
                              |
                              group: edgePaths (edges)
                              |
                              group: edgeLabels (edge labels)
                              |
                              group: nodes

All those SVG elements might contain other groups for each node, label, edge, or subgraph you add to the diagram. For each of them, Mermaid assigns special naming, which is not strictly dynamic. For example, it might use the same id name for all the flowcharts you are creating on the same page.

But you can always intervene in the SVG and add specific modifications. For example, if you don’t have any other SVG on the same page you are working on, you can modify all the Process shapes using the following styling on your page:

<style>
  .cssClass > rect {
    fill: #ff0000;
    stroke: #ffff00;
    stroke-width: 4px;
  }
style>

Notice that this is more about SVG than Mermaid, and deep diving into this is out of the scope of this article. I advise you to read more about SVGs if you want to know how to post-process Mermaid diagrams with additional features once you have created a diagram.

I also recommend reading the Mermaid API usage section in the Mermaid documentation to better understand how to apply JavaScript to Mermaid configurations and diagram manipulation.

Conclusion

This article introduced you to the basics of Mermaid for creating flowcharts. We covered an overview of Mermaid, flowchart syntax, shapes, links, subgraphs, themes, and styling options. Key tips and examples, including some not found in the documentation, are included to help you learn the syntax.

With this guide, you should feel confident using Mermaid to integrate flowcharts into your workflow. Flowcharts are a valuable visual tool for improving understanding, and Mermaid makes creating them quick and easy.

To explore further, consider diving deeper into Mermaid's library for other diagram types, advanced customization, and interactivity. If you need more help, check out my other article on building flowcharts. Happy coding!

How to Make Flowcharts and Bring Joy to your Coding

evaristo.c — Mon, 13 Jan 2025 14:18:01 +0000

Coding can be intense. Especially when you are knee-deep in debugging or trying to map complex projects. For many developers — novice and pros alike — it is not uncommon to spend hours staring at code, looking for answers that won’t come.

You may have tried every trick you know but still feel lost. But have you tried creating a visual representation of the problem so you can see how the code actually works?

I’m talking about using a flowchart.

In this article, you’ll learn how flowcharts work along with some common symbols and labels you can use in your flowcharts. We’ll also discuss some popular diagramming tools you can use to create flowcharts more easily. Finally, we’ll walk through how to actually build a flowchart so you can start using them in your projects.

What is a Flowchart?
A Flowchart’s Symbology, the Limitations of Symbols, and Solutions
Common Symbols and Labels Used in Flowcharts
How to Add Shapes to Your Flowchart: Generalization vs Refinement
Popular Diagramming Tools for Creating Flowcharts
How to Build a Flowchart – Methodology and Example
Conclusion

What is a Flowchart?

Simply put, a flowchart is a diagrammatic representation of an algorithm. It’s called a flowchart because it not only represents the steps but also depicts the direction the “job” flows as tasks are transferred to the next entity.

In many cases, a flowchart is considered part of a larger family of diagrams, usually referred to as flow diagrams. And although both names are commonly used, we’ll stick to the use of flowcharts to represent algorithms for now.

Here’s an example of a flowchart:

You’ll notice that it uses certain different shapes and colors – we’ll discuss these further below.

How Common Are Flowcharts These Days?

“Aren’t they from the time of, like, Cobol?” you might ask. Well, yes they are – and from even before that. Flow diagrams were quite popular from their introduction in the 1920’s all the way to the 1970’s. But their use started to fall off soon after that.

So you might wonder: are developers actually using flowcharts – or any kind of diagram – nowadays? I did some quick research across different developer community chats. I found that while not all devs say they use flowcharts, many of them mentioned that they were important in helping them sketch a vizualization of the code or the system.

I also found that senior developers were less interested in the use of diagrams because they usually knew the algorithms or the codebase almost by heart. But newer developers who were exposed to a codebase for the first time, revisiting a forgotten algorithm, or those needing to share some code with others tended to use flowcharts more often.

Why Do Devs Use Flowcharts?

Here are some of the most common reasons developers use flowcharts these days:

Focus: A visual resource to help you think about a problem.
Planning: Map out your steps before diving in.
Sharing standard processes: As a tool to facilitate the reading of standard processes.
Communicating and teaching: Explaining your code to both technical and non-technical people.
Documenting: Keep track of your work in a way that’s easy to follow.
Analysing existing code: Break down your code and others’ to see what’s really going on.

Of course, there are other methods you could use to cope with the situations listed above. But there are advantages to using flowcharts over other methods that have to do with the way we process information in our brain.

Still, making flowcharts is an intellectual process that entails some risks, particularly when it comes to clarifying information. So we need the right tools and a methodology to work with them.

In the following sections, we will go through all those points in more detail:

The semiotic of the flowchart – that is, the use of symbols to convey information. We’ll also discuss the role of the flowchart as an information tool, its limitations, and how to address them.
The most common symbols, their meanings, and how to use them
The intellectual processes of constructing flowcharts and their risks
A methodology to help you reduce those risks
The available tools to create flowcharts with a quick introduction to the one we will use for our examples

A Flowchart’s Symbology, the Limitations of Symbols, and Solutions

Earlier, I defined a flowchart as a diagram of sequences of steps, or workflow, of an algorithm. But we can also understand the flowchart as a “language”: when using a flowchart, we are translating the description of an algorithm from a verbal / textual language to a more symbolic one.

In other words, we can define a flowchart as a visualization of a streamlined workflow where we identify steps and relations by substituting meaningful symbols for verbal / textual descriptions.

How Symbols Work

What are the advantages of using a visualization based on symbols to understand an algorithm?

Physically, our brain has to make more of an effort to extract meaning from either text or numbers than it does from visual attributes and shapes. For example, after some learning and under the relevant context, it is easy to get the meaning of this street sign:

This sign may work better than writing a board explaining that drivers should be careful as there are kids crossing the road.

In our example, if you have to pause to read the explanatory board, by the time you learn what the message is it could be too late. But our brain makes a faster evaluation of the situation when presented with the sign after some training.

Also, visual attributes and shapes can not only refer to concrete, tangible objects, but also to concepts and actions. For example, if you have done arithmetics before, you’ll know the meaning of the following symbols:

When we use a symbol to convey meaning, whether concrete or intangible, we usually talk about semiosis. Semiosis is the process of producing and interpreting signs and symbols to convey meaning. It involves the interaction between a symbol, its meaning, and the person or machine interpreting it. This process is central to the communication, understanding, and creation of knowledge in both people and machines.

Symbolic communication takes advantage of our innate visual processing skills. This helps reduce the need for long-winded explanations because the observer has learned somehow what the sign means. Instead of “semiosis”, some people prefer the term abstraction to refer to the same process.

That it is what we do with flowcharts: abstracting meanings through symbols.

The value of semiotics in a visualization is substantial. Using meaningful symbols in a visualization such as a flowchart allows you and your audience to focus on patterns that written text, such as code or a script, can’t easily tell or describe.

And that is where the power of visualizations like flowcharts resides.

But flowchart symbols are not operators like you’d find in mathematics. Rather, they’re representations. In fact, they might represent something specific to the person who draws them.

Because of this, the symbols alone are often insufficient to fully convey abstract concepts. For example, the term "database” can represent many types of systems or technologies, and can have many different setups and uses. Also, as technology evolves, some symbols may lose their relevance.

To address this, clear textual explanations should accompany the shapes, ensuring the flowchart remains meaningful and avoids vagueness. You can also add styling and even images to strengthen the symbols’ meaning.

Common Symbols and Labels Used in Flowcharts

When creating a flowchart, you can use custom symbols, but it’s typically a good idea to stick to certain conventions. Conventions ensure better communication as well as consistency of messaging across different flowcharts.

The ANSI/ISO standards list more than 30 recognized flowchart shapes, though their usage isn’t strictly regulated. This allows vendors and developers to agree on best practices.

Since these symbols require textual and styling support anyway, some devs argue that you can reduce the number of shapes to a “necessary few” versatile symbols instead. I refer to these as "wildcards”. Wildcards can represent broader abstractions when paired with clear text and or styling. But don’t hesitate to use other standard symbols if you think that they bring more clarity to your flowchart.

For our example, we will focus on the most common shapes. Some of the most common and most versatile shapes are:

As you can see in the table above, we have the following shapes:

Oval (a start or end point)
Arrow (a connector that shows relationships between shapes)
Parallelogram (an input or output)
Rectangle (a process)
Diamond (a decision)

Let’s go through each of these now and examine how they work and how to use them.

The Terminator (Oval) Shape

This is the oval shape, called the start/end shape. It marks the starting and ending points of the process/system. The oval indicates the beginning or end result of the workflow, and the potential outcomes of a path.

Many devs use the oval shape, along with the words “start” and “end/stop/finish” for clarity.

Some people prefer to use a single circle to represent the start and a double circle to represent the end of a flowchart:

I personally prefer the circle – but it’s up to you. Just make sure you pick one and stick with it for consistency.

The Arrow or Flowline Shape

Also called the link or the edge by vendors and practitioners, this shape represents the connection between two steps. Also depending on its shape, it might indicate if that flow is broken, failed, or if it is an alternate path or process, and more.

The most common representation is the arrow, which indicates the direction of the workflow between two steps. The arrow points in the direction of the next step in the process.

When working with flowcharts, I accompany arrow flowlines and any other flowline with concise descriptions about the next step, sometimes with information about variables and, when it makes sense, the current state.

The Process (Rectangle) Shape

You can represent a process using a rectangle in a flowchart. It’s also referred to as a box:

A box can represent a single step, like an expression (for example, x = y*x²), a entire block statement, like “loop through array and update values by multiplying by 2”, or an entire sub-process, like an existing function or even a module.

The process shape is a proper wildcard and it can morph into many things, so it’s important to add a label to it and using text or other resources like formatting to clarify its meaning.

The Decision (Diamond) Shape

The decision is represented by a diamond. It is an abstraction for a condition’s test, a YES/NO, or TRUE/FALSE question. It is the equivalent of an IF/ELSE statement in coding.

The text accompanying this shape is a question formulating a comparison between an entering value and a control value. The flowchart usually splits into different branches depending on the answer or consequences after you use the decision shape:

The result of the decision box determines the next step in the process workflow. It’s usually declared to only answer a simple question, but you can abstract the question so it looks similar to an IF/ELSE IF/ … /ELSE control statement in coding, with lines representing different decisions.

When one of the flows returns to the decision shape from where it left, we are talking about a loop:

The interpretation is like asking to test the condition again after going through some steps along a specific workflow branch, then checking if the answer has changed.

The Input/Output (Parallelogram) Shape

The input/output shape is typically accompanied by the following text:

Either “input” or “output”, so you know which is being represented. You can also write other similar words like “get” / “put”, “in” / “out”, and so on.
An input or an output could be related to a variable that you are planning or you already have in your code. If that variable should have an expected type when either entering as input or output, I would also add the type.
Its corresponding state, as long as it provides more clarity to the flowchart.
Optionally, it would be also useful to mention the source of the input / output. Is it a dataset? A manual entry? A form? Will it be printed in the console?

Notice that the whole point of the use of this shape is to trace the entry or the exit of data into or out of the process. Therefore, this shape is valuable when you want to have at least an idea of data exchange.

Finally, a less common symbol, but one that I use often is…

The Preparation (Hexagon) Symbol

The preparation symbol is represented by an hexagon and it abstracts the setup for the following step. I usually use this shape to declare all the initial conditions when the workflow begins. I accompany this shape with a list of variables, their types, and even functions or initial event settings, like event listeners, together with their initial values.

Now that you understand the basics of the symbols, you may be wondering how to insert them into the diagram.

Especially for large diagrams, you’ll want to be very intentional about adding shapes. You’ll need to make careful decisions about placing and the number of shapes you’ll use, otherwise your flowchart could become unreadable.

You’ll need to make decisions about things like:

where to place the shapes so it results in a tidy flowchart.
which of those shapes are essential to the understanding of the workflow, and which are not.

Placing is perhaps the most difficult task of making a flowchart. If you are manually constructing your flowchart, unfortunately there’s not a simple formula that instructs you where to place the shapes in order to prevent overlapping. It’s up to you to visually resolve the placement and to decide when any overlap makes your diagram unreadable.

As you’ll see later, there are computationally-based solutions for the placing of shapes. But there is a simple rule that applies to all cases: the smaller the flowchart, the easier it is to place the shapes. So reducing the number of shapes and only including the key shapes is key to creating a clear flowchart.

Keep in mind that I’m not suggesting that you try to create the most minimalistic flowchart you can. Just that you try to make the simplest one that conveys enough information to help you understand the workflow.

How to Choose Which Shapes to Use

Deciding which shapes to use can turn into an iterative process of adding, moving, or removing text or symbols into or out of the flowchart.

There are two competing tendencies here: generalization and refinement.

For example, the next figure shows three different flowcharts that demonstrate how to use a coffee machine:

In the image above, you can see that the example on the left is the one with less explanations and fewer shapes, while the one on the right has more details.

In the same way, depending on your needs and the specific details you want to get out of the visualization, the flowchart can be more generalized or it can be more refined. In fact, it might acquire some elements of subjectivity, which usually rely on the amount of information and knowledge you have about the process before looking at the flowchart.

Generalization:

In the case of flowcharts, generalization, also known as lifting, is when you enclose several steps into a few words and / or symbols. There are two reasons to use a more generalized approach:

You and your audience are competent enough to complete the information not provided by the flowchart.
You and your audience don’t know much about that specific step.

In the second case, there are two situations you might be dealing with:

Even if you don’t know much about that part of the process, you can keep that step generalized because that step plays a small role in providing information that’s essential to you. Or,
The point is critical for you to understand the process, but you and your audience simply don’t know more.

It’s in the second situation when you have to try to “open the box”. And this is done through refinement.

Refinement consists of adding more steps and more words and symbols in order to add more detail to a procedure. It usually follows researching and studying.

When you’re refining your flowchart, this doesn’t necessarily mean that you know absolutely nothing about the procedure. What you’re looking for is something that allows you to point to specific details, and what comes before and what comes next.

But how much generalization is helpful? And how much refinement?

When your flowchart is too general, it results in a simpler visualization but it doesn’t contain much information. You might have to use more words or rely on inner knowledge in order to explain what the chart or a step means. The first flowchart in the previous image is the most generalized of all of them.

The risk of over-generalization is non-information.

The process of refinement involves the opposite risk, and is, in my view, more dangerous. If you don’t control the refinement process, you might end up with an absolute mess, like this:

The above diagram isn’t a flowchart, but the risk is the same. The risk of excessive refinement is noise.

There are several rules and mechanisms that help you prevent reaching an unnecessary level of either refinement or abstraction. This is what we are going to learn in the next sections. But first, let’s take a quick look at the available tools you can use to make diagrams and flowcharts.

Popular Diagramming Tools for Creating Flowcharts

Now that you know the shapes, what they are for, and have some idea about how to use them, you can start building a flowchart.

But before doing so, I’m going to make a short detour to talk about the tools you can use to build flowcharts.

Nowadays, the options are many. You can use online as well as offline resources. Some are specialized for building diagrams, while others are more general. Some you can access for free, and others are more for enterprise operations and come with high fees.

Below, you’ll find a quick table categorizing some of the dedicated tools I have used in the past or that I have been investigating recently.

Dedicated Solutions for Drawing Flowcharts

CATEGORY	HOW	EXAMPLES (free)
Drag and Drop	Shapes are manually dragged into a editor screen, linked with connectors and filled with relevant text.	draw.io
Scriptable	A script is written with a dedicated syntax for shapes, relationships, and text. The flowchart is automatically rendered and updated after changing the script.	Mermaid, PlantUML
AI-based	A descriptive prompt or even code is provided to the AI. The AI analyzes the content, usually recoding into a scriptable diagram before rendering it.	codetoflow.ai, ChatGPT plugins
Parser	Map (binary) code into dedicated graphical solutions based on established syntax rules.	drgarbagetools for Java in Eclipse, graphdracula for JQuery

No-code or low code tools:

The large majority of the existing specialized diagramming tools are designed to help people without coding skills.

When using these types of tools, you have to manually construct the diagram by dragging-and-dropping shapes into an (online) editor: you select the shape and move it around until you find your preferred place for it on the screen. There are functionalities to draw the flowlines (“connectors”) also by a dragging action, and you can always edit the shapes to add text or styling.

Script-based tools:

But there are also some less well-known tools that have been around for a while that are rising in popularity now: the script-based options. With these kinds of tools, you describe the shapes and relationships by scripting them according to the syntax of the tool.

These kinds of tools have the relative advantage that the diagram will be drawn for you on a rendering screen or image. An algorithm will try to find the best place for your shapes on the screen without you having to place them manually.

AI tools:

Then there are the AI tools. Many of those tools are based on the scripting tools. Some of them work as follows:

the AI interprets either a descriptive prompt or the code itself
Then it translates the prompt into a script using a scriptable diagramming tool
The diagram renders according to the AI-generated code.

I’ve found that these AI tools are still not quite up to the task for more complex projects – but they can come handy if you just want a quick solution. One that I have used is codetoflow.io, but there are also (guess what…) ChatGPT plugins you can use.

Parsers

Even before the AI tools came around, there were the parsers. They map steps and relationships into shapes based on well-established syntax rules. Some of those parsers are turning to AI instead, as the AI generators are easier to program and require less maintenance. But sometimes the rule-based parsers can be more precise if the rules they are based on remain without changes.

Some of those tools read on binary code, which is a better proxy to follow the full workflow, something that popular AI tools are not capable of. Some IDEs, like Eclipse, allow you to add plugins to draw a flowchart of your code based on binaries. One example is drgarbagetools which works only for Java in Eclipse.

General-purpose tools:

Apart from those dedicated tools, you can always use others that are not specifically built for diagramming. I have used PowerPoint and Google Slides in the past, and there are other presentation applications that support the ANSI / ISO shapes’ catalogue. You can also use tools like Figma, Miro, or others. There are too many others to list here.

And finally, there is always pen a paper.

Our Example: Using Mermaid.js

For the example in this tutorial, I’ll be using one of the scripting tools called Mermaid. One reason for using a script-based tool is the ease with which you can update the flowchart along the way. And this will come in handy when we reach the generalization / refinement step.

Although other tools do not hinder the generalization/refinement process, the fact that you might find yourself redoing the whole flowchart manually could become quite time consuming. With a script-based tool, you can focus mostly on writing down the right relationships and shapes, while you let the program place the shapes for you.

Although I’m using Mermaid here, I’m not prescribing the use of any particular tool for the examples ahead. You can use the one that suits your needs and with which you feel the most comfortable. None of them are perfect, and they all have their own merits.

But if you want to learn more about Mermaid, I’ve written another tutorial for you that’ll give you a general overview of the tool and how to use it. I will also provide the syntax I am using to create the examples so you can try it yourself.

How to Build a Flowchart – Methodology and Example

When building a flowchart, you can follow these steps:

Define the scope of your flowchart
Find the start of the workflow
Trace the workflow to the end while using high levels of generalization for the steps
Select what should be refined and what can be left generalized
Iterate: Research. Refine. Test. Research. Refine or Generalize. Test. Research. Refine or Generalize…
Enhance
Extend (optional)

Step 1: Define the Scope of Your Flowchart

It’s important to be clear about what you want to do with your flowchart. Is it representing a full codebase or just a fragment of a script? Is it an algorithm that you want to study or is it an analysis of some existing code? Do you want a detailed explanation of a workflow or just look at the relationships?

Having a clear goal for your flowchart will help you guide its construction.

For this example, we are going to use an exercise from freeCodeCamp’s curriculum:

const character = "#";
const count = 8;
const rows = [];

for (let i = 0; i < count; i = i + 1) {
  rows.push(character.repeat(i + 1))
}

let result = ""

for (const row of rows) {
  result = result + row + "\n";
}

console.log(result);

Our purpose here is to understand this code, particularly to gain more insights about the for-loops.

Step 2: Find the Start of the Workflow

Once you have an idea of what you want to do with your flowchart, try to figure out the point from where the workflow begins. If it involves analyzing existing code, bear in mind that the start of the workflow might not be at the start of your target code. Just keep in mind that whatever triggers the whole procedure, that is an indication that the “start” is there.

The workflow usually starts with the setting of the initial declarations and values, so we could say that our flowchart could start like this for this example:

flowchart TD
start((start)) --> |variable declaration| varDeclaration{{"*character*(str) 
                                          *count*(num) 
                                          *rows*(list) 
                                          *result*(str)"}}
varDeclaration -.-> C["..."]

Step 3: Trace the Workflow to the End and Use High Levels of Generalization in Each Step

Once you’ve found the starting point, try to systematically trace the workflow steps from start to end. If there are procedures along the way, you can compact them into more generalized steps using no more than two shapes.

The most common shape for depicting a generalized step is the process shape. Candidates to keep generalized are functions, control statement blocks like loops or if-statements, modules, or even libraries. Labels of those steps should consist of general descriptions of the things that are happening or should happen at that step.

For our example, we can represent our workflow and in particular the for-loops at a general level like this:

flowchart TD
start((start)) --> |variable declaration| varDeclaration{{"*character*(str) 
                                          *count*(num) 
                                          *rows*(list) 
                                          *result*(str)"}}
varDeclaration -->|"Use *character* and *count* to fill the *rows* list through a for-loop with strings"| forloop01["for-loop01 with *count* as control: str.repeat(*character*) --> *rows*.push(str)"]
forloop01 --> |"Use the updated *rows* list to create a new *result* string"| forloop02["for-loop02 along *rows* items: 
*row* --> 
*result* = *result* + *row* + '\n'"]
forloop02 --print output to the console--> consolelog["console.log(*result*)"]
consolelog --> stop(((stop)))

Stop for a while and review the schema you’ve created. Once you have a picture of the whole workflow, you’ll want to decide which sections might require more details.

In our case, we’ll refine the parts of the flowchart that deal with the two for-loops. Describing a for-loop is a typical example when learning to create flowcharts, but I also realized that the two for-loops in our exercise are not of the same type. So I thought it would be interesting to see if the flowchart can reveal how they compare.

Step 5: Time to Iterate (Research, Refine or Generalize. Test. Repeat.)

What you’ve prepared up to Step 4 is a general sketch of the workflow. Now it’s time to dig into the areas where more detail is required. During this process, sometimes you’ll find yourself coming back to an abstraction while looking for the clearest way forward with your flowchart.

There are two things that will help you in this process:

New Shapes: this is the time when you may want to use some other shapes. Start with the most common ones. Use other shapes as long as you can give them a clear role in your flowchart and they help you reduce a long explanation about what the replaced shape does.
Text: Extend the use of text to explain the workflow. It should be more specific to the algorithm itself.

This process ends when you are satisfied with the clarity and level of detail of your flowchart. But there are a best practices that allow you to control the process:

Try to keep everything to a single page.
Keep the number of shapes to around 20 per page.
Avoid line-crossing more than 4 times. Use connectors when that happens. Having to explain 5 or more connections is likely not a good thing.

After any change, test your flowchart. Testing is the most subjective aspect of the methodology. There might not be a way to test the flowchart result against a tangible outcome.

If that makes you uncomfortable, try to think in the following way: the flowchart can be seen as a sort of ordered TODO list or brainstorm notes describing what the code or system should do in order to accomplish a desired task.

A flowchart is similar to this TODO list. But instead of writing all those steps as comments or even pseudo-code, you are using (conventional) symbols.

But barring the advances of AI or any use of flow-based programming, comments are not code, no matter how detailed they are.

So the decision of whether the flowchart is working or not is left to you and your audience. The most important question to resolve here is: is the information provided by the flowchart enough to understand what you need to understand about the process? Is it revealing something new? Is it helping you organize your ideas more clearly?

If you are still not satisfied, then repeat the process. But don’t feel like you have to stick to this process alone. You can always stop this effort and look for another way to explain your procedures if you find that a flowchart won’t work for you.

You could facilitate the refining and the clarity of the output by doing some additional research. Try to find how other people describe the procedure you are about to work on. Is there something about the language that you should keep in mind? Whenever possible, don’t start from scratch.

Also, try to be faithful as much as possible to the actual way in which the procedure should be coded, especially if you are refining. But don’t forget that it’s a representation. Feel free to work on a draft when not enough information is available.

Let’s go back to our example. I did some quick research to find out how others might interpret a for-loop in a flowchart. I found this reference useful to guide my own description:

This approach seems to be fairly standard and I will try to include some of those steps in my flowchart. I also found that according to JavaScript documentation, the kind of for-loop we are about to represent repeats until a specified condition evaluates to false, just like in the flowchart above.

Let’s start by working on the first for-loop only:

flowchart TD
    start((start)) --> |variable declaration| varDeclaration{{"`*character*(str)
    *count*(num)
    *rows*(list)
    *result*(str)`"}}
    varDeclaration --> |**Start First Loop**: entering initial values of *i* and *count*| inputToLoop01[/"`input: 
                                                                                                            *count* = 8
                                                                                                            *i* = 0
                                                                                                            `"/] 
    inputToLoop01 --> forLoop01{"`Is *i* < *count*?`"}
    forLoop01 -.NO: something happens..-> stop(((stop)))
    forLoop01 --> |YES| inputI[/"`input: *i*`"/]
    inputI --> |"`create strings of length (*i* + 1) from *character*`"| repeatStr["**new string** = character.repeat(i+1)"]
    repeatStr --> |"`add newly created string 
            at the end of *rows* list`"| pushToRows["`rows.push(**new string**)`"]
    pushToRows --> |"`bottom of the block: update *i*`"| updateI[/i = i+1/]
    updateI --> |evaluate condition| forLoop01

Perfect.

Let’s now focus on the second for-loop. It turns out that it’s syntactically different from the previous one. And in fact, there are different kinds of loops in programming. The one we refined earlier is usually known as the “traditional” one, or better a numeric range type for-loop. The second one is an iterator type for-loop.

An iterator is a functionality that moves incrementally along a group of values or items. That functionality can have subprocesses to initialize the iterator – one to get the current value the iterator is pointing to, as well as a subprocess to go to the next one.

Also, remember that a for-loop stops repeating a workflow branch as soon as the condition evaluates to false.

Let’s try to reflect all this knowledge when refining the second for-loop. I will generalize the first for-loop for the sake of clarity:

flowchart TD
    start((start)) --> |variable declaration| varDeclaration{{"`*character*(str)
    *count*(num)
    *rows*(list)
    *result*(str)`"}}
    varDeclaration --> |**Start Range-Based Loop**: entering initial values of *i* and *count*| forLoop01["Range-Based For-Loop"]
    forLoop01 -- enter Iterator-Based For-Loop --> inputToLoop02[/"`INPUT:
                                                                *rows* (list of str of size *count*)
                                                                *result* (empty str)`"/]
    something --> stop(((stop)))
    inputToLoop02 --> forLoop02{"`Are there still *rows*' items?`"}
    forLoop02 --> |YES: get the current one| row[/"GET: *row* = currentItem(*rows*)"/]
    row --> |"concatenate the current *row* item plus a line (\n) to the current value of *result*"| newStr["**new string** = *result* + *row* + '\n'"]
    newStr --> |change the value of *result* for **new string**|newRes[*result* = **new string**]
    newRes --> |"`bottom of the block: move to next item`"| updateR[/"nextItem(*rows*)"/]
    updateR --> forLoop02
    forLoop02 --> |NO: we exhausted all the items| something

Now we have a clear flowchart for each of the for-loops! We had to first understand what the loops were about, and then had to find a way to represent them. We used refinement and generalization to expand / contract the information rendered by the flowchart.

At the end, we just have to accept that these are still approximations — in order to get how those for-loops really work, we would have to go learn more about JavaScript, probably looking through the JavaScript source code, or even closer to the machine by analysing binaries. But I’m personally satisfied with the information I got from the analysis.

Now after making these changes, we can come back and merge both flowcharts (for each of the for-loops) to complete the full representation of the code:

flowchart TD
    start((start)) --> |variable declaration| varDeclaration{{"`*character*(str)
    *count*(num)
    *rows*(list)
    *result*(str)`"}}
    varDeclaration --> |**Start Range-Based For-Loop**: entering initial values of *i* and *count*| inputToLoop01[/"`INPUT: 
                                                                                                            *count* = 8
                                                                                                            *i* = 0
                                                                                                            `"/] 
    inputToLoop01 --> forLoop01{"`Is *i* < *count*?`"}
    forLoop01 --> |YES| inputI[/"`GET: *i*`"/]
    inputI --> |"`create strings of length (*i* + 1) from *character*`"| repeatStr["**new string** = character.repeat(i+1)"]
    repeatStr --> |"`add newly created string 
            at the end of *rows* list`"| pushToRows["`rows.push(**new string**)`"]
    pushToRows --> |"`bottom of the block: update *i*`"| updateI[/i = i+1/]
    updateI --> |evaluate condition| forLoop01
    forLoop01 -->|NO| outputRows[/"`OUTPUT: *rows* list of string items of size *count*`"/]
    outputRows --> |**Start Iterator-Based For-Loop**: entering initial values of *rows* and *result*| inputToLoop02[/"`INPUT:
                                                                *rows* (list of str of size *count*)
                                                                *result* (empty str)`"/]
    inputToLoop02 --> forLoop02{"`Are there still *rows*' items?`"}
    forLoop02 --> |YES: get the current one| row[/"GET: *row* = currentItem(*rows*)"/]
    row --> |"concatenate the current *row* item plus a line (\n) to the current value of *result*"| newStr["**new string** = *result* + *row* + '\n'"]
    newStr --> |change the value of *result* for **new string**|newRes[*result* = **new string**]
    newRes --> |"`bottom of the block: move to next item`"| updateR[/"nextItem(*rows*)"/]
    updateR --> forLoop02
    forLoop02 --> |NO: we exhausted all the items| outputResult[/"`OUTPUT: *result* (str)`"/]
    outputResult --> |"`display *result* on the console`"|displayResult["`console.log(*result*)
            fa:fa-display`"]
    displayResult --> stop(((stop)))

Step 6: Enhance the Flowchart

Sometimes, specially with large flowcharts, the repeated use of similar shapes requires additional enhancement to provide more clarity. Normally you won’t quite know what you need to enhance until you have the full picture of something more final.

One way to do this is by grouping sections of the workflow. For that, you can use styling, like coloring the shapes, to highlight similar or related steps. It can also be helpful to highlight elements in the workflow that are really playing a fundamental role in the analysis.

You can also create groups of sub-procedures by boxing them (that is, placing a box around related elements of the flowchart).

Let’s apply some enhancements to our final flowchart by boxing and coloring:

flowchart TD
    start((start)) --> |variable declaration| varDeclaration{{"`*character*(str)
    *count*(num)
    *rows*(list)
    *result*(str)`"}}
    varDeclaration --> |**Start Range-Based For-Loop**: entering initial values of *i* and *count*| inputToLoop01[/"`INPUT: 
                                                                                                            *count* = 8
                                                                                                            *i* = 0
                                                                                                     `"/]:::input 
    subgraph RANGE_BASED_LOOP
    inputToLoop01 --> forLoop01{"`Is *i* < *count*?`"}
    forLoop01 --> |YES| inputI[/"`GET: *i*`"/]:::get
    inputI --> |"`create strings of length (*i* + 1) from *character*`"| repeatStr["**new string** = character.repeat(i+1)"]
    repeatStr --> |"`add newly created string 
            at the end of *rows* list`"| pushToRows["`rows.push(**new string**)`"]
    pushToRows --> |"`bottom of the block: update *i*`"| updateI[/i = i+1/]:::input
    updateI --> |evaluate condition| forLoop01
    end
    forLoop01 -->|NO| outputRows[/"`OUTPUT: *rows* list of string items of size *count*`"/]:::output
    outputRows --> |**Start Iterator-Based For-Loop**: entering initial values of *rows* and *result*| inputToLoop02[/"`INPUT:
                                                                *rows* (list of str of size *count*)
                                                                *result* (empty str)`"/]:::input
    subgraph ITERATOR_BASED_LOOP
    inputToLoop02 --> forLoop02{"`Are there still *rows*' items?`"}
    forLoop02 --> |YES: get the current one| row[/"GET: *row* = currentItem(*rows*)"/]:::get
    row --> |"concatenate the current *row* item plus a line (\n) to the current value of *result*"| newStr["**new string** = *result* + *row* + '\n'"]
    newStr --> |change the value of *result* for **new string**|newRes[*result* = **new string**]
    newRes --> |"`bottom of the block: move to next item`"| updateR[/"nextItem(*rows*)"/]:::input
    updateR --> forLoop02
    end
    forLoop02 ---> |NO: we exhausted all the items| outputResult[/"`OUTPUT: *result* (str)`"/]:::output
    outputResult --> |"`display *result* on the console`"|displayResult[/"`console.log(*result*)
            fa:fa-display`"/]
    displayResult -->|finish| stop(((stop)))

    style start fill:black, color:#fff
    style displayResult fill: #DFFF73
    style stop fill:grey, color:#fff, stroke: white
    classDef input fill:#F8D192
    classDef get fill:#F8D062
    classDef output fill:#ECF892

Step 7: Extend the Flowchart

This step is optional. If you have done what you can to keep the flowchart as clear as possible – but you are finding that it still needs more refinement – you may be dealing with a complex process.

In this case, it’s time to think about a separate flowchart to continue or extend the one you are working on. There are ways to indicate the connection between pages. You can also show a section of a flowchart as a generalization and show a more refined flowchart on a separate pages using references.

I won’t go into the details of how to do that here, as this article is long enough as it is. And in this case, I think we can keep our flowchart to just one page, so I won’t go further with creating new pages for it.

So we are done!

Conclusion

When making a flowchart, we are not looking to imitate our code. Rather, we’re looking to understand it. This means that the flowchart has to be clear.

And if you use your flowcharts correctly, along with the right tools, they can help you reveal patterns and hidden operations, as well as stay organized, reduce overwhelm, and ultimately make coding feel more manageable. This will ultimately improve your coding skills and your state of mind.

So give flowcharts a try — you might be surprised at how much they can help you out.

evaristo.c - freeCodeCamp.org

How to Become an Analytical Programmer – Solve the "Rock, Paper, Scissors" Game 5 Ways Using JavaScript & Mermaid.js

How to Read this Article

Here’s what we’ll cover:

Visual Tools for Code Comparison

Why Use System Block Diagrams?

The Use Case-Driven System Block Diagram

What We Are Going to Do

The Code Examples

How to Choose Your Projects

The Scope

The Methodology

How We’ll Build the Diagrams

Our Tool: Mermaid.js

Five Code Examples of Rock, Paper, Scissors

1. “CPC Rock Paper Scissors” by Amit: A project with fireworks animations

Analysis of the Project

Quickly discovering of the start and end of the workflow

The playGame Event Handler

Refinement

Imperative Programming

Finalizing the diagram

2. “Rock paper scissors game using native drag & drop” by Hmz C: A project using the HTML Drag element

Analysis of the Project

Quickly discovering of the start and end of the workflow

IIFE

Refinement

Finalizing the diagram and comparison to previous project

3. “Rock Paper Scissors” by Brad Traversy: A project with a modal and a reset

Analysis of the Project

Quickly discovering of the start and end of the workflow

Refinement

The play event handler as a Controller

Modularity and Separatation of Concerns (SoC)

Procedural Programming

Finalizing the diagram and comparison to previous projects

4. “Rock Paper Scissors OOP” by Damian: A project written in OOP

Analysis of the Project

Quickly discovering the start and end of the workflow

Refinement

OOP Encapsulation

Finalizing the diagram and comparison to previous projects

5. “Recurrent Neural Network – Rock, Paper, Scissors” by Andrew Worcerster: A Project Implementing AI

Analysis of the Project

Quickly discovering of the start and end of the workflow

Refinement

Further Refinement

Finalizing the diagram and comparison to previous projects

Final Thoughts

How to Use the Mermaid JavaScript Library to Create Flowcharts

Table of Contents

What is Mermaid?

Challenges with Mermaid

Getting Started with Mermaid

How to Start Your Flowchart in Mermaid

How to Write a Comment

How to Configure your Flowchart

Nodes and Shapes in Mermaid

How to Create Your First Node (The Process Shape)

How to Declare Shapes and Shape Labels with Mermaid: Two Different Syntaxes

Quick Look at the Most Typical Shapes

The Terminator Shape

The Arrow (Rectangle) Shape

The Input/Output (Parallelogram) Shape

The Process (Rectangle) Shape

The Decision (Diamond) Shape

Markdown and HTML in Mermaid

Edges (Relationships) and Edge Labels in Mermaid

Subgraphs

How to Add Styling with Mermaid

Directives or frontMatter?

Interactivity

Mermaid, CSS, and SVG

Conclusion

How to Make Flowcharts and Bring Joy to your Coding

Table of Contents

What is a Flowchart?

How Common Are Flowcharts These Days?

Why Do Devs Use Flowcharts?

A Flowchart’s Symbology, the Limitations of Symbols, and Solutions

The `playGame` Event Handler

The `play` event handler as a Controller