Skip to content

Table of Contents

Phase 1 — Research: Best Practices Synthesis

This document is the evidence base for how the rest of the repository is designed. Every structural decision below traces back to one of these findings.

Table of Contents

1. Go Engineering Best Practices

Canonical sources (read these first, in order)

  1. A Tour of Go — interactive syntax tour → https://go.dev/tour/
  2. How to Write Go Code — modules, packages, testing basics → https://go.dev/doc/code
  3. Effective Go — the idiom bible → https://go.dev/doc/effective_go
  4. Go Code Review Comments — the de-facto style guide → https://go.dev/wiki/CodeReviewComments
  5. Google Go Style Guide — the most complete modern style reference → https://google.github.io/styleguide/go/
  6. Standard library docs → https://pkg.go.dev/std
  7. The Go Memory Model → https://go.dev/ref/mem

Key idioms that recur in interviews and code review

  • Errors are values. Return error as the last value; wrap with fmt.Errorf("...: %w", err); inspect with errors.Is / errors.As. Never ignore an error without a comment. Avoid panic in library code.
  • Accept interfaces, return structs. Keep interfaces small (1–3 methods) and define them at the consumer, not the producer.
  • Zero values are useful. Design types so the zero value is usable (sync.Mutex, bytes.Buffer).
  • context.Context is first parameter, named ctx. Never store it in a struct. Use it for cancellation/deadlines/request-scoped values only.
  • Concurrency: "Don't communicate by sharing memory; share memory by communicating." But a sync.Mutex is often simpler — pick the clearer one. Every goroutine must have a known exit path (avoid leaks). Use errgroup for fan-out-with-errors, context for cancellation.
  • Channel axioms: send/recv on nil channel blocks forever; close of closed channel panics; send on closed channel panics; receive on closed channel returns the zero value immediately.
  • Prefer the standard library. net/http, database/sql, encoding/json, log/slog (structured logging, Go 1.21+), testing, context cover most needs.

Project layout

  • Small programs: a flat package is fine — don't over-structure early.
  • Larger services: follow the community golang-standards/project-layout (cmd/, internal/, pkg/, api/, configs/, deployments/). internal/ enforces encapsulation at compile time.
  • Architecture for services: Hexagonal / Ports & Adapters (a.k.a. Clean Architecture) — domain logic in the center, adapters (HTTP, gRPC, DB, cache) on the edges, dependencies point inward. Wire dependencies explicitly (constructor injection); reach for google/wire only when manual wiring hurts.

Testing, performance, security, ops

  • Testing: table-driven tests + subtests (t.Run), t.Parallel(), httptest, benchmarks (testing.B), fuzzing (testing.F), and integration tests with testcontainers-go. Aim for meaningful coverage, not 100%.
  • Performance: measure first with pprof and benchmarks; understand escape analysis (go build -gcflags=-m), allocation reduction, sync.Pool, and the GC. Don't optimize without a profile.
  • Security: govulncheck, gosec, parameterized SQL, validate all input, never log secrets, use crypto/* not hand-rolled crypto, manage secrets via env/secret manager.
  • Observability: structured logs (slog), metrics (Prometheus client_golang), tracing (OpenTelemetry). Add /healthz + /readyz. Implement graceful shutdown (signal.NotifyContext + http.Server.Shutdown).
  • Deployment: multi-stage Docker builds → tiny static images (FROM scratch/distroller), CGO_ENABLED=0, build with -ldflags="-s -w"; ship via GitHub Actions CI/CD.

2. Learning Methodology

Technique What it is How this repo uses it
Active Recall Retrieve from memory instead of re-reading Every day ends with self-quiz questions; interview/ bank uses <details> to hide answers
Spaced Repetition Review at increasing intervals PROGRESS.md review schedule; weekly + monthly review templates re-surface old topics
Deliberate Practice Targeted practice at the edge of ability with feedback exercises/ graded by difficulty; "Mistakes Made" section forces feedback loops
Project-Based Learning Learn by building real things projects/ track, beginner → production capstone
Feynman Technique Explain simply to expose gaps Daily "Explain it like I'm 5" reflection field
Learning by Teaching Teaching cements understanding Notes are written for other learners; the repo is public
Atomic Notes One idea per note, densely linked journal/ day notes + NOTES.md knowledge base of small linked concepts
Progressive Summarization Distill notes in layers over time Day note → weekly review → monthly review → cheatsheet
Knowledge Graph Link concepts to see structure [[wikilink]]-style cross-links between notes and a skill matrix

Adopted core loop: Read → Build → Explain → Recall → Review. Daily learning uses Project-Based Learning + Feynman; retention uses Active Recall + Spaced Repetition; mastery is proven by Deliberate Practice and teaching (public notes).

3. GitHub Repository Best Practices

  • README is the front door: badges, one-line pitch, what/why, table of contents, navigation map, quick start, progress snapshot, how to use the repo.
  • Community health files: LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md (optional for a journal), issue/PR templates in .github/.
  • Issues + Projects (board): track learning as work. Use a GitHub Project board (Backlog → This Week → In Progress → Review → Done) and Issue Forms for daily logs.
  • Milestones = the 6 months (or 24 weeks). Labels classify by type/area/difficulty/status.
  • Releases + Tags + CHANGELOG: tag the end of each month (v0.1.0 … v0.6.0); keep a Keep a Changelog-style CHANGELOG.md; write release notes summarizing the month.
  • Discussions/Wiki: Discussions for Q&A and "today I learned"; keep long-form canonical docs in-repo (versioned with code) rather than the Wiki.
  • Commits: small, frequent, Conventional Commits; green CI on main.
  • Automation: GitHub Actions for lint, link-check, spell-check, ToC, Go CI; Dependabot.

4. Documentation Best Practices

  • Diátaxis framework: separate Tutorials (learning), How-to guides, Reference (cheatsheets), and Explanation (notes/ADRs). This repo maps each to a directory.
  • Markdown discipline: one H1 per file, ToC for long docs, relative links between docs, fenced code blocks with language hints, tables for comparisons, callouts (>), and mermaid for diagrams.
  • Diagrams as code: prefer mermaid (renders on GitHub) for architecture, sequence, and ER diagrams; store image assets in assets/.
  • Architecture Decision Records (ADR): capture why behind decisions in docs/adr/ using the Michael Nygard template (Context → Decision → Consequences). Number them 0001-....
  • Findability: every directory has a README.md index; cross-link liberally; keep a consistent navigation footer.
  • Supporting docs: FAQ.md, troubleshooting sections, cheat sheets, and a glossary lower the barrier for readers.

5. Developer Portfolio Best Practices

What hiring managers actually scan for on a GitHub profile:

  1. Signal of real engineering, not tutorials copied verbatim — tests, CI, docs, commit history.
  2. A pinned, polished flagship project with a great README (problem, architecture diagram, how to run, screenshots, trade-offs).
  3. Code quality: idiomatic style, error handling, tests, linting, meaningful structure.
  4. Communication: clear writing in READMEs/ADRs demonstrates you can work on a team.
  5. Consistency: a steady commit history shows discipline (this repo's daily cadence is itself a portfolio artifact).
  6. Breadth + depth: breadth via topic coverage; depth via the capstone.

This repo demonstrates each: problem solving (exercises/algorithms), code quality (CI + tests + lint), documentation (this whole system), architecture (capstone + ADRs), testing (test strategy per project), Git usage (conventional commits, branches, tags, releases), and professional practices (issue/PR templates, changelog, automation).

6. Design Decisions Derived From This Research

Decision Driven by
Daily journal with recall + reflection fields Active Recall, Feynman, Deliberate Practice
Weekly + monthly review cadence Spaced Repetition, Progressive Summarization
projects/ beginner→capstone track Project-Based Learning, Portfolio flagship
Hexagonal architecture for the capstone Go service best practice, architecture signal
docs/adr/ decision log Documentation + architecture signal
Conventional Commits + monthly tags/releases GitHub best practice, Git-usage signal
GitHub Actions (lint/links/spell/Go CI) Repo automation, code-quality signal
Every folder has a README index + wikilinks Documentation findability, Knowledge Graph
Interview bank with hidden answers Active Recall / Retrieval Practice

⬅ Back to README · See the Roadmap