Skip to content

Commit 80e8982

Browse files
lucasbellesilucasbellesi
committed
Add Java foundations MVP
1 parent b71cbca commit 80e8982

49 files changed

Lines changed: 1850 additions & 189 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/cpp-build.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,12 @@ jobs:
3131
with:
3232
dotnet-version: "8.0.x"
3333

34+
- name: Setup Java
35+
uses: actions/setup-java@v4
36+
with:
37+
distribution: "temurin"
38+
java-version: "21"
39+
3440
- name: Install clang-format
3541
run: |
3642
sudo apt update
@@ -71,6 +77,12 @@ jobs:
7177
with:
7278
dotnet-version: "8.0.x"
7379

80+
- name: Setup Java
81+
uses: actions/setup-java@v4
82+
with:
83+
distribution: "temurin"
84+
java-version: "21"
85+
7486
- name: Install g++
7587
run: |
7688
sudo apt update
@@ -111,6 +123,12 @@ jobs:
111123
with:
112124
dotnet-version: "8.0.x"
113125

126+
- name: Setup Java
127+
uses: actions/setup-java@v4
128+
with:
129+
distribution: "temurin"
130+
java-version: "21"
131+
114132
- name: Setup MSYS2
115133
uses: msys2/setup-msys2@v2
116134
with:

‎CONCEPT_INDEX.md‎

Lines changed: 45 additions & 45 deletions
Large diffs are not rendered by default.

‎CONTRIBUTING.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ Thank you for contributing to this repository.
99
- Use clear English for all text, comments, and instructions.
1010
- Maintain cross-platform compatibility (Windows MSYS2 + Linux).
1111
- Keep Node-based tooling simple and explicit when touching the TypeScript track.
12+
- Keep Java foundations on plain `javac`/`java` until the track intentionally adopts build tooling.
1213

1314
## Workflow
1415

@@ -52,12 +53,13 @@ For large changes, you can run one language at a time before the full check:
5253

5354
- `python scripts/automation.py check-exercise-output-contracts --language python`
5455
- `python scripts/automation.py check-exercise-output-contracts --language go`
56+
- `python scripts/automation.py check-exercise-output-contracts --language java`
5557
- `python scripts/automation.py check-exercise-output-contracts --language typescript`
5658
- `python scripts/automation.py check-exercise-output-contracts --language cpp`
5759
- `python scripts/automation.py check-exercise-output-contracts --language csharp`
5860

5961
These smoke checks also compile standalone C# exercises by generating temporary validation projects during the check.
60-
TypeScript checks restore Node dependencies from `package-lock.json`, compile with `tsc`, and execute the emitted JavaScript with `node`.
62+
TypeScript checks restore Node dependencies from `package-lock.json`, compile with `tsc`, and execute the emitted JavaScript with `node`. Java checks compile single-file programs with Java 21 using `javac` and run them with `java`.
6163

6264
The public PowerShell and Bash scripts are thin wrappers over the shared Python automation core in `scripts/automation.py`. Curriculum validation and smoke target metadata live in `scripts/automation_manifest.json`.
6365
The artifact cleanup command removes generated build outputs, reports, temporary binaries, and exercise report files while keeping restored dependencies such as `node_modules`.
@@ -82,7 +84,7 @@ Use [EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md](EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md)
8284
- `## Checkpoint`
8385
- Every project or assessment checkpoint should include:
8486
- `README.md`
85-
- runnable entrypoint (`main.cs` + `.csproj`, `main.go`, `main.py`, or `main.ts`)
87+
- runnable entrypoint (`main.cs` + `.csproj`, `main.go`, `Main.java`, `main.py`, or `main.ts`)
8688
- the same learner goal, input/output shape, and acceptance expectations as the corresponding C++ checkpoint
8789
- required `## Learning Metadata` before `## Quick Run` with `Difficulty`, `Estimated Time`, `Prerequisites`, and `Learning Focus`
8890
- recommended `## Cross-Language Notes` before `## What To Check`
@@ -97,6 +99,7 @@ Use [EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md](EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md)
9799
- Avoid external dependencies and test frameworks for C++ modules.
98100
- Avoid external dependencies and test frameworks for non-C++ checkpoints.
99101
- Keep the TypeScript track on plain Node console programs; do not introduce browser, DOM, or framework dependencies.
102+
- Keep the Java foundations MVP on package-free single-file programs; do not introduce Maven, Gradle, or `src/main/java` yet.
100103
- Keep examples aligned with C++17.
101104
- Keep documentation in English and keep path names consistent with folder names.
102105
- Keep parity planning updated in `LANGUAGE_PARITY_MATRIX.md` when adding modules or checkpoints to non-C++ tracks.

‎LANGUAGE_PARITY_MATRIX.md‎

Lines changed: 49 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,74 +1,77 @@
11
# Language Parity Matrix
22

3-
This matrix tracks module and checkpoint parity across C++, C#, Go, Python, and TypeScript.
3+
This matrix tracks module and checkpoint parity across C++, C#, Go, Java, Python, and TypeScript.
44

55
- Canonical order is defined by the C++ track.
66
- C++, C#, Go, Python, and TypeScript now reach module and checkpoint parity through `04-expert`.
7+
- Java currently tracks `01-foundations` as a Java 21 MVP.
78
- Status labels:
89
- `Done`: module implemented with example, exercises, and README.
910
- `Planned`: module not implemented yet, already queued in order.
1011

1112
## Foundations (`01-foundations`)
1213

13-
| Module | C++ | C# | Go | Python | TypeScript |
14-
| --- | --- | --- | --- | --- | --- |
15-
| types-and-io | Done | Done | Done | Done | Done |
16-
| operators-and-expressions | Done | Done | Done | Done | Done |
17-
| control-flow | Done | Done | Done | Done | Done |
18-
| functions | Done | Done | Done | Done | Done |
19-
| arrays-and-vectors | Done | Done | Done | Done | Done |
20-
| strings | Done | Done | Done | Done | Done |
21-
| scope-and-lifetime-basics | Done | Done | Done | Done | Done |
22-
| formatted-output-and-iomanip | Done | Done | Done | Done | Done |
14+
| Module | C++ | C# | Go | Java | Python | TypeScript |
15+
| --- | --- | --- | --- | --- | --- | --- |
16+
| types-and-io | Done | Done | Done | Done | Done | Done |
17+
| operators-and-expressions | Done | Done | Done | Done | Done | Done |
18+
| control-flow | Done | Done | Done | Done | Done | Done |
19+
| functions | Done | Done | Done | Done | Done | Done |
20+
| arrays-and-vectors | Done | Done | Done | Done | Done | Done |
21+
| strings | Done | Done | Done | Done | Done | Done |
22+
| scope-and-lifetime-basics | Done | Done | Done | Done | Done | Done |
23+
| formatted-output-and-iomanip | Done | Done | Done | Done | Done | Done |
2324

2425
## Core (`02-core`)
2526

2627
Current parity progress in non-C++ tracks:
2728

2829
- C#: `6/6` modules complete
2930
- Go: `6/6` modules complete
31+
- Java: `0/6` modules complete
3032
- Python: `6/6` modules complete
3133
- TypeScript: `6/6` modules complete
3234

33-
| Order | Module | C++ | C# | Go | Python | TypeScript |
34-
| --- | --- | --- | --- | --- | --- | --- |
35-
| 1 | input-validation | Done | Done | Done | Done | Done |
36-
| 2 | algorithms-basics | Done | Done | Done | Done | Done |
37-
| 3 | file-io-basics | Done | Done | Done | Done | Done |
38-
| 4 | sorting-and-searching | Done | Done | Done | Done | Done |
39-
| 5 | maps-and-frequency-counting | Done | Done | Done | Done | Done |
40-
| 6 | error-handling-and-defensive-programming | Done | Done | Done | Done | Done |
35+
| Order | Module | C++ | C# | Go | Java | Python | TypeScript |
36+
| --- | --- | --- | --- | --- | --- | --- | --- |
37+
| 1 | input-validation | Done | Done | Done | Planned | Done | Done |
38+
| 2 | algorithms-basics | Done | Done | Done | Planned | Done | Done |
39+
| 3 | file-io-basics | Done | Done | Done | Planned | Done | Done |
40+
| 4 | sorting-and-searching | Done | Done | Done | Planned | Done | Done |
41+
| 5 | maps-and-frequency-counting | Done | Done | Done | Planned | Done | Done |
42+
| 6 | error-handling-and-defensive-programming | Done | Done | Done | Planned | Done | Done |
4143

4244
## Advanced and Expert
4345

4446
Current parity progress in non-C++ tracks:
4547

4648
- C#: `5/5` modules complete in `03-advanced`, `5/5` in `04-expert`
4749
- Go: `5/5` modules complete in `03-advanced`, `5/5` in `04-expert`
50+
- Java: `0/5` modules complete in `03-advanced`, `0/5` in `04-expert`
4851
- Python: `5/5` modules complete in `03-advanced`, `5/5` in `04-expert`
4952
- TypeScript: `5/5` modules complete in `03-advanced`, `5/5` in `04-expert`
5053

5154
### Advanced (`03-advanced`) - Current Expansion Queue
5255

53-
| Order | Module | C++ | C# | Go | Python | TypeScript |
54-
| --- | --- | --- | --- | --- | --- | --- |
55-
| 1 | structs-and-classes | Done | Done | Done | Done | Done |
56-
| 2 | constructors-and-invariants | Done | Done | Done | Done | Done |
57-
| 3 | copy-and-move-semantics | Done | Done | Done | Done | Done |
58-
| 4 | inheritance-and-polymorphism | Done | Done | Done | Done | Done |
59-
| 5 | templates-basics | Done | Done | Done | Done | Done |
56+
| Order | Module | C++ | C# | Go | Java | Python | TypeScript |
57+
| --- | --- | --- | --- | --- | --- | --- | --- |
58+
| 1 | structs-and-classes | Done | Done | Done | Planned | Done | Done |
59+
| 2 | constructors-and-invariants | Done | Done | Done | Planned | Done | Done |
60+
| 3 | copy-and-move-semantics | Done | Done | Done | Planned | Done | Done |
61+
| 4 | inheritance-and-polymorphism | Done | Done | Done | Planned | Done | Done |
62+
| 5 | templates-basics | Done | Done | Done | Planned | Done | Done |
6063

61-
`04-expert` projects and assessments are now implemented across all active non-C++ tracks.
64+
`04-expert` projects and assessments are now implemented across all active non-Java tracks.
6265

6366
### Expert (`04-expert`)
6467

65-
| Order | Module | C++ | C# | Go | Python | TypeScript |
66-
| --- | --- | --- | --- | --- | --- | --- |
67-
| 1 | memory-management-and-raii | Done | Done | Done | Done | Done |
68-
| 2 | smart-pointers-in-depth | Done | Done | Done | Done | Done |
69-
| 3 | concurrency-basics | Done | Done | Done | Done | Done |
70-
| 4 | performance-and-profiling-basics | Done | Done | Done | Done | Done |
71-
| 5 | modularization-and-build-structure | Done | Done | Done | Done | Done |
68+
| Order | Module | C++ | C# | Go | Java | Python | TypeScript |
69+
| --- | --- | --- | --- | --- | --- | --- | --- |
70+
| 1 | memory-management-and-raii | Done | Done | Done | Planned | Done | Done |
71+
| 2 | smart-pointers-in-depth | Done | Done | Done | Planned | Done | Done |
72+
| 3 | concurrency-basics | Done | Done | Done | Planned | Done | Done |
73+
| 4 | performance-and-profiling-basics | Done | Done | Done | Planned | Done | Done |
74+
| 5 | modularization-and-build-structure | Done | Done | Done | Planned | Done | Done |
7275

7376
## Checkpoint Parity
7477

@@ -79,18 +82,18 @@ Status labels:
7982

8083
### Projects
8184

82-
| Checkpoint | C++ | C# | Go | Python | TypeScript |
83-
| --- | --- | --- | --- | --- | --- |
84-
| 01-foundations | Done | Done | Done | Done | Done |
85-
| 02-core | Done | Done | Done | Done | Done |
86-
| 03-advanced | Done | Done | Done | Done | Done |
87-
| 04-expert | Done | Done | Done | Done | Done |
85+
| Checkpoint | C++ | C# | Go | Java | Python | TypeScript |
86+
| --- | --- | --- | --- | --- | --- | --- |
87+
| 01-foundations | Done | Done | Done | Planned | Done | Done |
88+
| 02-core | Done | Done | Done | Planned | Done | Done |
89+
| 03-advanced | Done | Done | Done | Planned | Done | Done |
90+
| 04-expert | Done | Done | Done | Planned | Done | Done |
8891

8992
### Assessments
9093

91-
| Checkpoint | C++ | C# | Go | Python | TypeScript |
92-
| --- | --- | --- | --- | --- | --- |
93-
| 01-foundations | Done | Done | Done | Done | Done |
94-
| 02-core | Done | Done | Done | Done | Done |
95-
| 03-advanced | Done | Done | Done | Done | Done |
96-
| 04-expert | Done | Done | Done | Done | Done |
94+
| Checkpoint | C++ | C# | Go | Java | Python | TypeScript |
95+
| --- | --- | --- | --- | --- | --- | --- |
96+
| 01-foundations | Done | Done | Done | Planned | Done | Done |
97+
| 02-core | Done | Done | Done | Planned | Done | Done |
98+
| 03-advanced | Done | Done | Done | Planned | Done | Done |
99+
| 04-expert | Done | Done | Done | Planned | Done | Done |

‎README.md‎

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
This repository teaches programming through small runnable examples and focused exercises.
66

7-
- Five active language tracks: C++, C#, Go, Python, and TypeScript.
7+
- Six active language tracks: C++, C#, Go, Java, Python, and TypeScript.
88
- Shared concept naming across tracks for easier comparison.
99
- Each module follows the same shape: `README.md`, `example/main.*`, and two exercises.
1010
- Each implemented level ends with a project and an assessment checkpoint.
@@ -19,6 +19,7 @@ For the full local pipeline, install:
1919
- Go
2020
- .NET 8 SDK
2121
- Node LTS with `npm`
22+
- Java 21 JDK
2223

2324
If you only want to learn one track, follow that track README first because language-specific prerequisites differ.
2425

@@ -30,11 +31,12 @@ If you only want to learn one track, follow that track README first because lang
3031
- [C++ Guide](languages/cpp/README.md)
3132
- [C# Guide](languages/csharp/README.md)
3233
- [Go Guide](languages/go/README.md)
34+
- [Java Guide](languages/java/README.md)
3335
- [Python Guide](languages/python/README.md)
3436
- [TypeScript Guide](languages/typescript/README.md)
3537
2. Start at the first roadmap for that track:
3638
- C++: [00-setup](languages/cpp/00-setup/README.md), then `01-foundations`
37-
- C#, Go, Python, TypeScript: `01-foundations`
39+
- C#, Go, Java, Python, TypeScript: `01-foundations`
3840
3. Run one module example.
3941
4. Solve `exercises/01` and `exercises/02` in that module.
4042
5. Mark progress in the language checklist.
@@ -53,6 +55,7 @@ If you only want to learn one track, follow that track README first because lang
5355
| C++ | 00-setup, 01-foundations, 02-core, 03-advanced, 04-expert | Foundations, Core, Advanced, Expert, projects, assessments | Most complete and primary track |
5456
| C# | 01-foundations, 02-core, 03-advanced, 04-expert | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 5/5 expert modules, 4/4 projects, 4/4 assessments | Module and checkpoint parity complete through expert |
5557
| Go | 01-foundations, 02-core, 03-advanced, 04-expert | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 5/5 expert modules, 4/4 projects, 4/4 assessments | Module and checkpoint parity complete through expert |
58+
| Java | 01-foundations | 8/8 foundations modules | Java 21 MVP; core, advanced, expert, projects, and assessments planned |
5659
| Python | 01-foundations, 02-core, 03-advanced, 04-expert | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 5/5 expert modules, 4/4 projects, 4/4 assessments | Module and checkpoint parity complete through expert |
5760
| TypeScript | 01-foundations, 02-core, 03-advanced, 04-expert | 8/8 foundations modules, 6/6 core modules, 5/5 advanced modules, 5/5 expert modules, 4/4 projects, 4/4 assessments | Module and checkpoint parity complete through expert |
5861

@@ -80,6 +83,13 @@ dotnet run --project languages/csharp/01-foundations/types-and-io/example/types-
8083
go run languages/go/01-foundations/types-and-io/example/main.go
8184
~~~
8285

86+
### Java
87+
88+
~~~bash
89+
javac -d build/java languages/java/01-foundations/types-and-io/example/Main.java
90+
java -cp build/java Main
91+
~~~
92+
8393
### Python
8494

8595
~~~bash
@@ -105,6 +115,7 @@ learn-programming-languages-with-examples/
105115
cpp/
106116
csharp/
107117
go/
118+
java/
108119
python/
109120
typescript/
110121
~~~
@@ -133,7 +144,7 @@ A standardized `## Learning Metadata` block is required before `## Quick Run` fo
133144
Checkpoint artifacts under `languages/<language>/projects/*` and `languages/<language>/assessments/*` should mirror the corresponding C++ checkpoint style:
134145

135146
- `README.md`
136-
- runnable entrypoint (`main.cpp` in C++, `main.cs` + `.csproj` in C#, `main.go` in Go, `main.py` in Python, or `main.ts` in TypeScript)
147+
- runnable entrypoint (`main.cpp` in C++, `main.cs` + `.csproj` in C#, `main.go` in Go, `main.py` in Python, or `Main.java` in Java foundations; `main.ts` in TypeScript)
137148
- same learner goal, input/output shape, and acceptance expectations as the C++ version
138149

139150
## Example Commenting Standard
@@ -160,7 +171,7 @@ bash ./scripts/verify-repo.sh
160171
bash ./scripts/lint.sh
161172
~~~
162173

163-
`verify-repo` validates curriculum structure, the blocking education-quality gate, output contracts, and compiled-language builds. `lint` validates formatting and static checks for C++, Python, Go, C#, and TypeScript.
174+
`verify-repo` validates curriculum structure, the blocking education-quality gate, output contracts, and compiled-language builds. `lint` validates formatting and static checks for C++, Python, Go, C#, Java, and TypeScript.
164175

165176
Use narrower commands only when you want a faster loop on one area:
166177

@@ -198,13 +209,13 @@ bash ./scripts/clean-artifacts.sh
198209
bash ./scripts/verify-repo.sh
199210
~~~
200211

201-
GitHub Actions validates links, README structure, module completeness, checkpoint completeness, documentation sync, compiled-language builds, multi-language smoke checks, and Linux lint checks for C++, Python, Go, C#, and TypeScript.
212+
GitHub Actions validates links, README structure, module completeness, checkpoint completeness, documentation sync, compiled-language builds, multi-language smoke checks, and Linux lint checks for C++, Python, Go, C#, Java, and TypeScript.
202213

203214
The public PowerShell and Bash scripts remain the supported entrypoints, but they now delegate to a shared Python automation core under `scripts/automation.py` backed by `scripts/automation_manifest.json`.
204215

205216
Use `clean-artifacts` when you want to remove generated build outputs, reports, temporary binaries, and exercise report files without removing dependencies such as `node_modules`.
206217

207-
The multi-language smoke scripts also compile standalone C# exercises by generating temporary validation projects during the check and compile TypeScript programs before executing their smoke targets.
218+
The multi-language smoke scripts also compile standalone C# exercises by generating temporary validation projects during the check and compile TypeScript programs before executing their smoke targets, and compile Java single-file programs with Java 21.
208219

209220
Use [EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md](EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md) to keep entry examples pedagogically consistent during reviews. The education audit command is advisory and writes markdown/json findings without failing CI.
210221
Use [EDUCATIONAL_ANTI_PATTERN_BACKLOG.md](EDUCATIONAL_ANTI_PATTERN_BACKLOG.md) for the prioritized anti-pattern vs corrected-example expansion plan.
@@ -220,7 +231,7 @@ Documentation sync also validates that [CONCEPT_INDEX.md](CONCEPT_INDEX.md) cove
220231
For long exercise-contract runs, you can scope by language:
221232

222233
~~~bash
223-
python scripts/automation.py check-exercise-output-contracts --language typescript
234+
python scripts/automation.py check-exercise-output-contracts --language java
224235
~~~
225236

226237
## Contributing

‎languages/cpp/MODULE_README_STYLE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ Use this structure for every concept module under:
55
- `languages/cpp/01-foundations`, `02-core`, `03-advanced`, `04-expert`
66
- `languages/csharp/01-foundations` and newer implemented levels
77
- `languages/go/01-foundations` and newer implemented levels
8+
- `languages/java/01-foundations` and newer implemented levels
89
- `languages/python/01-foundations` and newer implemented levels
910

1011
This structure is required for all implemented concept modules.

‎languages/java/01-foundations/README.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Java Foundations
2+
3+
## Learning Metadata
4+
5+
- Difficulty: Beginner.
6+
- Estimated Time: 5-7 hours.
7+
- Prerequisites: Java 21 JDK installed; terminal basics.
8+
- Study Strategy: Run each example, change one value, then solve both exercises before moving to the next module.
9+
10+
## Module Order
11+
12+
1. [types-and-io](./types-and-io/README.md)
13+
2. [operators-and-expressions](./operators-and-expressions/README.md)
14+
3. [control-flow](./control-flow/README.md)
15+
4. [functions](./functions/README.md)
16+
5. [arrays-and-vectors](./arrays-and-vectors/README.md)
17+
6. [strings](./strings/README.md)
18+
7. [scope-and-lifetime-basics](./scope-and-lifetime-basics/README.md)
19+
8. [formatted-output-and-iomanip](./formatted-output-and-iomanip/README.md)
20+
21+
## Level Outcomes
22+
23+
- Compile and run single-file Java programs with `javac` and `java`.
24+
- Read console input with `Scanner` and convert it into typed values.
25+
- Use branches, loops, methods, arrays, lists, strings, scope, and formatted output.
26+
- Compare Java's explicit types and class structure with the other language tracks.
27+
28+
## Done When
29+
30+
- [ ] I ran every `example/Main.java` file.
31+
- [ ] I completed both exercises in every foundations module.
32+
- [ ] I can explain where `public class Main` and `public static void main` fit in a Java program.
33+
- [ ] I can compile a Java file into a temporary output directory and run it with `java -cp`.

0 commit comments

Comments
 (0)