How Language-Specific Code Implementations Are Organized in the Hello-Algo Codes Directory

The hello-algo repository structures its codes/ directory using a three-tier locale → language → module hierarchy that separates documentation by spoken language while maintaining parallel algorithm implementations across Python, Java, C++, TypeScript, Swift, and Zig.

The krahets/hello-algo repository serves as the official code companion to the "Hello Algorithm" book, storing executable examples in a rigorous directory layout. This organization enables localized documentation for English, Japanese, and Traditional Chinese readers while keeping codebases synchronized across six programming languages.

The Three-Tier Hierarchy: Locale, Language, and Module

Locale Directories (en, ja, zh-hant)

The repository root contains locale folders such as en/, ja/, and zh-hant/. Each locale houses both the book's documentation (docs/) and its corresponding codes/ directory, ensuring that code examples align with the specific language version of the text. This design allows the same algorithm to exist in en/codes/ and ja/codes/ with identical internal structures but contextually appropriate documentation.

Programming Language Folders

Inside each locale's codes/ directory, you'll find language-specific folders including python/, java/, cpp/, swift/, typescript/, and zig/. These folders contain all source files for that programming language, with identical algorithms implemented in parallel across locales. For example, the path en/codes/typescript/ contains the same algorithmic coverage as ja/codes/python/, differing only in implementation language.

Modules, Utils, and Chapter Organization

Every language directory contains two critical subfolder types that organize the source code:

• modules/ or utils/ – Reusable data-structure utilities such as Vertex, TreeNode, ListNode, and PrintUtil. Note that TypeScript exclusively uses modules/ (e.g., en/codes/typescript/modules/TreeNode.ts), while Java, C++, Swift, and Zig typically use utils/ (e.g., en/codes/java/utils/TreeNode.java).
• chapter_* – Algorithm implementations grouped by topic, such as chapter_sorting/, chapter_tree/, and chapter_dynamic_programming/.

Cross-Language File Naming Conventions

Algorithms follow a strict one-file-per-implementation rule using identical base names across languages. For example, quicksort appears as quick_sort.ts in TypeScript, quick_sort.py in Python, and quick_sort.java in Java, enabling direct comparison between en/codes/typescript/chapter_sorting/quick_sort.ts and ja/codes/python/chapter_sorting/quick_sort.py.

Directory Structure Illustration

The following tree demonstrates the parallel organization between TypeScript (using modules/) and Swift (using utils/) implementations:

/en
 └─/codes
     ├─/typescript
     │   ├─ modules/
     │   │   ├─ Vertex.ts
     │   │   ├─ TreeNode.ts
     │   │   └─ ListNode.ts
     │   └─ chapter_sorting/
     │       ├─ quick_sort.ts
     │       └─ merge_sort.ts
     └─/swift
         ├─ utils/
         │   ├─ Vertex.swift
         │   └─ ListNode.swift
         └─ chapter_sorting/
             └─ quick_sort.swift

This pattern repeats identically under ja/codes/ and zh-hant/codes/, ensuring that the structural organization remains consistent whether you are examining the Japanese Python implementation or the Traditional Chinese Zig version.

Code Implementation Examples

The repository maintains consistent data structure definitions across languages. Below are the ListNode implementations from three different language folders, illustrating the naming and structural conventions used throughout the codebase.

TypeScript: en/codes/typescript/modules/ListNode.ts

export class ListNode<T> {
  constructor(public value: T, public next: ListNode<T> | null = null) {}
}

// Example usage
import { ListNode } from "./ListNode";

const head = new ListNode(1, new ListNode(2, new ListNode(3)));
let cur: ListNode<number> | null = head;
while (cur) {
  console.log(cur.value);
  cur = cur.next;
}

Python: ja/codes/python/modules/list_node.py

class ListNode:
    def __init__(self, val, nxt=None):
        self.val = val
        self.next = nxt

# Example usage

head = ListNode(1, ListNode(2, ListNode(3)))
cur = head
while cur:
    print(cur.val)
    cur = cur.next

Swift: en/codes/swift/utils/ListNode.swift

public class ListNode<T> {
    public var value: T
    public var next: ListNode<T>?

    public init(_ value: T, _ next: ListNode<T>? = nil) {
        self.value = value
        self.next = next
    }
}

// Example usage
let head = ListNode(1, ListNode(2, ListNode(3)))
var cur: ListNode<Int>? = head
while let node = cur {
    print(node.value)
    cur = node.next
}

Key Source Files and Locations

The repository follows predictable paths for core data structures across all supported languages:

• TypeScript: Utilities reside in en/codes/typescript/modules/ (e.g., Vertex.ts, TreeNode.ts), while algorithms live in chapter_* folders like chapter_sorting/quick_sort.ts.
• Python: Modules are stored in ja/codes/python/modules/ (e.g., tree_node.py, list_node.py), with algorithms following the same chapter-based organization.
• Java: Uses en/codes/java/utils/ for shared structures like TreeNode.java, differing from TypeScript's modules/ naming convention.
• C++: Header files such as tree_node.hpp sit in ja/codes/cpp/utils/, maintaining consistency with Java's folder naming.
• Swift: Implements utilities in en/codes/swift/utils/ (e.g., TreeNode.swift, ListNode.swift).
• Zig: Stores node definitions in zh-hant/codes/zig/utils/ (e.g., TreeNode.zig), completing the cross-language coverage.

This standardized layout enables modular reuse of utilities within each language while supporting side-by-side comparison of algorithm implementations across the entire repository.

Summary

• The hello-algo repository uses a locale → language → module hierarchy under codes/ to organize implementations for English, Japanese, and Traditional Chinese readers.
• Locale folders (en/, ja/, zh-hant/) separate documentation while maintaining parallel code structures across all programming languages.
• Language directories (python/, java/, cpp/, typescript/, swift/, zig/) contain identical algorithm implementations using consistent file naming conventions.
• Utility modules live in modules/ (TypeScript) or utils/ (other languages), providing shared data structures like TreeNode and ListNode that are imported by chapter algorithms.
• Chapter folders (chapter_sorting/, chapter_tree/, etc.) group algorithms by topic, enabling direct cross-language comparison of files with identical base names.

Frequently Asked Questions

Why does the repository organize code by locale rather than using a single global codes directory?

The locale-based structure allows the repository to maintain synchronized translations of the "Hello Algorithm" book while keeping code examples contextually aligned with each language version. This separation ensures that documentation references and comments match the specific regional release without mixing localized content or creating naming conflicts.

What is the difference between the modules/ and utils/ folders?

Both folders serve identical purposes—storing reusable data-structure utilities such as Vertex, TreeNode, and PrintUtil—but the naming convention varies by programming language. According to the source code analysis, TypeScript exclusively uses modules/, while Java, C++, Swift, and Zig consistently use utils/ for these shared components.

How can I compare the same algorithm across different programming languages?

Navigate to the corresponding chapter_* folder in each language directory under the same locale (e.g., en/codes/). Files share identical base names across languages, such as quick_sort.py, quick_sort.java, and quick_sort.ts, making it straightforward to locate and compare implementations side-by-side using the parallel folder trees.

Are the code implementations identical across all supported languages?

While the underlying algorithm logic remains consistent, implementations respect each language's idioms and type systems. For example, Python uses dynamic typing in list_node.py while Swift employs generics in ListNode.swift, but the structural organization and file naming remain uniform across all six supported languages as implemented in krahets/hello-algo.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}