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

> Explore the hello-algo codes directory organization: a locale language module hierarchy for parallel algorithm implementations across Python Java C++ TypeScript Swift and Zig.

- Repository: [Yudong Jin/hello-algo](https://github.com/krahets/hello-algo)
- Tags: internals
- Published: 2026-02-25

---

**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`](https://github.com/krahets/hello-algo/blob/main/en/codes/typescript/modules/TreeNode.ts)), while Java, C++, Swift, and Zig typically use `utils/` (e.g., [`en/codes/java/utils/TreeNode.java`](https://github.com/krahets/hello-algo/blob/main/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`](https://github.com/krahets/hello-algo/blob/main/quick_sort.ts) in TypeScript, [`quick_sort.py`](https://github.com/krahets/hello-algo/blob/main/quick_sort.py) in Python, and [`quick_sort.java`](https://github.com/krahets/hello-algo/blob/main/quick_sort.java) in Java, enabling direct comparison between [`en/codes/typescript/chapter_sorting/quick_sort.ts`](https://github.com/krahets/hello-algo/blob/main/en/codes/typescript/chapter_sorting/quick_sort.ts) and [`ja/codes/python/chapter_sorting/quick_sort.py`](https://github.com/krahets/hello-algo/blob/main/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:

```text
/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`](https://github.com/krahets/hello-algo/blob/main/en/codes/typescript/modules/ListNode.ts)

```typescript
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`](https://github.com/krahets/hello-algo/blob/main/ja/codes/python/modules/list_node.py)

```python
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`](https://github.com/krahets/hello-algo/blob/main/en/codes/swift/utils/ListNode.swift)

```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`](https://github.com/krahets/hello-algo/blob/main/Vertex.ts), [`TreeNode.ts`](https://github.com/krahets/hello-algo/blob/main/TreeNode.ts)), while algorithms live in `chapter_*` folders like [`chapter_sorting/quick_sort.ts`](https://github.com/krahets/hello-algo/blob/main/chapter_sorting/quick_sort.ts).
- **Python**: Modules are stored in `ja/codes/python/modules/` (e.g., [`tree_node.py`](https://github.com/krahets/hello-algo/blob/main/tree_node.py), [`list_node.py`](https://github.com/krahets/hello-algo/blob/main/list_node.py)), with algorithms following the same chapter-based organization.
- **Java**: Uses `en/codes/java/utils/` for shared structures like [`TreeNode.java`](https://github.com/krahets/hello-algo/blob/main/TreeNode.java), differing from TypeScript's `modules/` naming convention.
- **C++**: Header files such as [`tree_node.hpp`](https://github.com/krahets/hello-algo/blob/main/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`](https://github.com/krahets/hello-algo/blob/main/TreeNode.swift), [`ListNode.swift`](https://github.com/krahets/hello-algo/blob/main/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`](https://github.com/krahets/hello-algo/blob/main/quick_sort.py), [`quick_sort.java`](https://github.com/krahets/hello-algo/blob/main/quick_sort.java), and [`quick_sort.ts`](https://github.com/krahets/hello-algo/blob/main/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`](https://github.com/krahets/hello-algo/blob/main/list_node.py) while Swift employs generics in [`ListNode.swift`](https://github.com/krahets/hello-algo/blob/main/ListNode.swift), but the structural organization and file naming remain uniform across all six supported languages as implemented in `krahets/hello-algo`.