Learn Programming Languages With Examples

Project Overview

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

• Five active language tracks: C++, C#, Go, Python, and TypeScript.
• Shared concept naming across tracks for easier comparison.
• Each module follows the same shape: README.md, example/main.*, and two exercises.
• Each implemented level ends with a project and an assessment checkpoint.
• VS Code-first workflow, with scripts for Windows PowerShell and Bash.

Repo Prerequisites

For the full local pipeline, install:

• Python 3
• a C++17-capable g++
• Go
• .NET 8 SDK
• Node LTS with npm

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

Start Here

Learning Path

1. Choose your language guide:
   • C++ Guide
   • C# Guide
   • Go Guide
   • Python Guide
   • TypeScript Guide
2. Start at the first roadmap for that track:
   • C++: 00-setup, then 01-foundations
   • C#, Go, Python, TypeScript: 01-foundations
3. Run one module example.
4. Solve exercises/01 and exercises/02 in that module.
5. Mark progress in the language checklist.

Contributor Path

1. Read CONTRIBUTING.md.
2. Install the repo prerequisites listed above.
3. Run ./scripts/verify-repo.ps1 or bash ./scripts/verify-repo.sh as the default pre-PR check.
4. Use a narrower script only when you want a faster loop on one part of the repo.

Language Status

Language	Current Levels	Coverage	Track Status
C++	00-setup, 01-foundations, 02-core, 03-advanced, 04-expert	Foundations, Core, Advanced, Expert, projects, assessments	Most complete and primary track
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
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
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
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

Parity planning reference: LANGUAGE_PARITY_MATRIX.md Browse by concept: CONCEPT_INDEX.md

Run One Example Per Language

C++

g++ -std=c++17 -Wall -Wextra -pedantic languages/cpp/01-foundations/types-and-io/example/main.cpp -o types_and_io_cpp
./types_and_io_cpp

C#

dotnet run --project languages/csharp/01-foundations/types-and-io/example/types-and-io-example.csproj

Go

go run languages/go/01-foundations/types-and-io/example/main.go

Python

python languages/python/01-foundations/types-and-io/example/main.py

TypeScript

npm run build:typescript
node build/typescript/01-foundations/types-and-io/example/main.js

Repository Structure

learn-programming-languages-with-examples/
  .github/workflows/        # CI checks
  .vscode/                  # VS Code tasks and recommendations
  scripts/                  # Build, run, and documentation checks
  templates/                # Concept module templates
  languages/
    cpp/
    csharp/
    go/
    python/
    typescript/

Documentation Contract

All concept module README files under languages/<language>/<level>/<module>/README.md follow one required structure:

1. ## Quick Run
2. ## Topics Covered
3. ## Common Pitfalls
4. ## Exercise Focus
5. ### Exercise Specs
6. ## Checkpoint

Reference: Module README Style

A standardized ## Learning Metadata block is required before ## Quick Run for implemented modules and checkpoints. Implemented level READMEs should also include it before ## Module Order. Use these fields:

• modules: difficulty, estimated time, prerequisites, cross-language comparison guidance
• checkpoints: difficulty, estimated time, prerequisites, learning focus
• level READMEs: difficulty, estimated time, prerequisites, study strategy

## Cross-Language Notes is the recommended comparison section for new or substantially updated modules and checkpoints. Keep it short, concrete, and honest about where concepts do not map one-to-one.

Checkpoint artifacts under languages/<language>/projects/* and languages/<language>/assessments/* should mirror the corresponding C++ checkpoint style:

• README.md
• runnable entrypoint (main.cpp in C++, main.cs + .csproj in C#, main.go in Go, main.py in Python, or main.ts in TypeScript)
• same learner goal, input/output shape, and acceptance expectations as the C++ version

Example Commenting Standard

Hand-written example code files under languages/*/*/*/example/ should use intent-first comments to help new developers read code quickly:

• Start each file with a short header comment that explains what the example teaches.
• Place comments before meaningful logic blocks, validation paths, and output/verification sections.
• Use comments to explain concepts, tradeoffs, and language-specific adaptations, not obvious syntax.
• Keep comments short, practical, and in English.
• Avoid empty scaffolding comments such as Intent: or line-by-line narration.

Validation and CI

Use the full repository check by default:

./scripts/verify-repo.ps1

bash ./scripts/verify-repo.sh

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

./scripts/check-links.ps1
./scripts/check-readme-structure.ps1
./scripts/check-module-completeness.ps1
./scripts/check-checkpoint-completeness.ps1
./scripts/check-cross-language-parity.ps1
./scripts/check-exercise-parity.ps1
./scripts/check-example-output-contracts.ps1
./scripts/check-exercise-output-contracts.ps1
./scripts/audit-education-quality.ps1
./scripts/lint.ps1
./scripts/smoke-languages.ps1
./scripts/build-all.ps1
./scripts/verify-repo.ps1

bash ./scripts/check-links.sh
bash ./scripts/check-readme-structure.sh
bash ./scripts/check-module-completeness.sh
bash ./scripts/check-checkpoint-completeness.sh
bash ./scripts/check-cross-language-parity.sh
bash ./scripts/check-exercise-parity.sh
bash ./scripts/check-example-output-contracts.sh
bash ./scripts/check-exercise-output-contracts.sh
bash ./scripts/audit-education-quality.sh
bash ./scripts/lint.sh
bash ./scripts/smoke-languages.sh
bash ./scripts/build-all.sh
bash ./scripts/verify-repo.sh

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.

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.

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.

Use 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. Use EDUCATIONAL_ANTI_PATTERN_BACKLOG.md for the prioritized anti-pattern vs corrected-example expansion plan.

Documentation sync also validates that CONCEPT_INDEX.md covers every implemented module and checkpoint path listed in the automation manifest. Cross-language parity checks now validate module focus/teaching headers across tracks, exercise parity checks validate exercises/01 and exercises/02 alignment across tracks, and example plus exercise output contracts validate stable learner-visible output for smoke-targeted programs.

For long exercise-contract runs, you can scope by language:

python scripts/automation.py check-exercise-output-contracts --language typescript

Contributing

See CONTRIBUTING.md for contribution workflow and documentation requirements.

License

This project is licensed under the MIT License. See LICENSE.