Compendium

Languages — Per-Note Schema

3 min read

Languages — Per-Note Schema

Per-Note Schema

Every note in Languages/ MUST follow this structure. Predictability is the point — agents and humans should know where to look without reading the whole note.

Frontmatter

---
title: "<Language> — Reference"
created: <ISO 8601>
agent: claude-code
type: language-reference
language: <canonical name, e.g., "Python", "C++">
paradigms: [imperative, object-oriented, functional, ...]
typing: <static | dynamic | gradual | dependent>
memory: <gc | manual | rc | borrow-checked | ...>
compilation: <compiled | interpreted | jit | transpiled | ahead-of-time>
domains: [web, systems, data, ml, mobile, embedded, scripting, ...]
tags: [language-reference, <language-slug>, <paradigm-tags>, ...]
official_docs: <url>
spec: <url, if any>
latest_version: "<x.y.z (yyyy-mm)>"
---

Body sections (in order, all required)

1. At a glance

One screen of bullets: created year, current owner/foundation, paradigms, type system, memory model, compilation model, primary use cases, notable runtimes/implementations, latest stable version with date.

2. Getting started

  • Installation (official installer + version manager if standard)
  • Hello, world! example
  • Project layout convention
  • Package manager / build tool
  • REPL / playground if relevant

3. Basics

  • Primitive types & literals
  • Variables, mutability, scoping rules
  • Control flow (if/else, switch/match, loops)
  • Functions: signatures, defaults, varargs, closures, first-class status
  • Strings & string interpolation
  • Built-in collections (list/array, map/dict, set, tuple)

4. Intermediate

  • Type system depth (generics, inference, constraints, variance)
  • Modules / packages / namespaces
  • Error-handling model (exceptions, Result/Option/Either, panics, errno)
  • Concurrency primitives (threads, async, channels, coroutines)
  • File I/O and networking basics
  • Standard library highlights worth knowing

5. Advanced

  • Memory model & ownership / GC tuning knobs
  • Concurrency / parallelism deep dive (runtimes, schedulers, locks, atomics)
  • FFI / interop with C or other ecosystems
  • Reflection / introspection
  • Performance tuning (profiling tools, common hot paths)

6. God mode

  • Metaprogramming (macros, decorators, codegen, templates, type-level)
  • Compiler / runtime internals worth knowing
  • Bytecode / IR / disassembly tooling
  • Custom build phases, language extensions, plugins, embedding the runtime
  • The tricks that separate “writes the language” from “shapes the language”

7. Idioms & style

  • Naming conventions
  • Official formatter & linter
  • The community’s ineffable “-ic” patterns (Pythonic, Rusty, idiomatic Go)
  • What expert reviewers look for

8. Ecosystem

  • Most-used frameworks per domain (web, data, ML, mobile, GUI)
  • Testing tools
  • Documentation tools
  • Notable companies / projects using it

9. Gotchas

  • Common bugs & footguns
  • Surprising behaviors / WAT moments
  • Pitfalls for newcomers from other languages

10. Citations

  • Official docs (versioned URL when possible)
  • Language spec or reference
  • Style guide
  • Other authoritative sources used to write this note

Writing rules

  • Cite, don’t paraphrase from memory. Every non-trivial claim should trace to a citation in section 10.
  • Date version-sensitive claims. “As of YYYY-MM, latest stable is X.Y” — never just “latest is X.Y”.
  • Cross-link. Use [[Languages/<other>|<other>]] to link to comparable languages.
  • Show, don’t tell, for syntax. A 5-line code sample beats a paragraph of prose every time.
  • Stay opinionated about depth. “God mode” is the differentiator vs every other reference — make it count. Don’t pad it with intermediate material.

Graph View