Documentation

Table of Contents

  1. Code Comments
  2. Mini-Lesson Documentation
  3. Code Highlights
  4. Project Documentation

Documentation is about explaining your code, process, and learning journey. It helps others understand your work and supports collaboration.

Subrequirements

Code Comments

What was learned: Comments and documentation explain what code does and why, making it easier for others (and yourself) to understand and maintain projects. Good documentation helps teams collaborate and supports learning. Writing comments in Pong and summarizing homeworks showed how clear explanations improve every project. JSDoc comments for classes and methods follow a standard format that IDEs and documentation generators can read.
Evidence: 
// From hacks/pong.md — well-commented Config block explaining every setting
// -----------------------------
// Config: Tweak these values
// -----------------------------
const Config = {
    canvas: { width: 800, height: 500 },
    paddle: { width: 10, height: 100, speed: 10.5 },
    ball: { radius: 10, baseSpeedX: 5, maxSpeed: 15 },
    // TODO[Students]: Remap keys if desired
    keys: { p1Up: "w", p1Down: "s", p2Up: "ArrowUp", p2Down: "ArrowDown" },
    visuals: { bg: "#000", fg: "#fff", text: "#fff", gameOver: "red", win: "yellow" }
};

/**
 * Paddle — a moveable rectangle controlled by a player or AI.
 * @param {number} x - Horizontal position (pixels from left)
 * @param {number} y - Vertical position (pixels from top)
 * @param {number} boundsHeight - Canvas height, used to clamp movement
 */
class Paddle {
    constructor(x, y, width, height, speed, boundsHeight) {
        this.position     = new Vector2(x, y);
        this.width        = width;
        this.height       = height;
        this.speed        = speed;
        this.boundsHeight = boundsHeight;
    }
}

Code Runner Challenge

Hit Run to see JSDoc-style comments in action. The code logs each method's documentation description alongside its result — the same commenting density (>10%) required for the CS111 code review.

Lines: 1 Characters: 0
Output
Click "Run" in code control panel to see output ...

Quick Quiz: Code Comments

  1. Why are comments important in code?
    • a) They make code run faster
    • b) They help explain what the code does
    • c) They are required for all variables
  2. What is a JSDoc comment?
  3. How can comments help you when you revisit your code later?
Show Answers 1. b) They help explain what the code does 2. A special comment format that documents functions, classes, and parameters for tools and IDEs. 3. They remind you (or others) what the code is doing and why, making it easier to update or debug.

Mini-Lesson Documentation

What was learned: Mini-lesson documentation means creating a comic, visual post, or blog with an embedded runtime game demo that teaches a concept. This combines writing, visuals, and working code into a single shareable post. Building the Night at the Museum blog and the Pong hack post showed how to present technical ideas in an engaging, accessible way.
Evidence: 
// From hacks/pong.md — Student Challenges section documents learning objectives inline
// -----------------------------------------
// Student Challenges (inline TODO checklist)
// -----------------------------------------
// 1) Make it YOUR game: change colors in Config.visuals, dimensions/speeds in Config.
// 2) Add AI: implement simple tracking for right paddle in handleInput. DONE
// 3) Rally speed-up: every time the ball hits a paddle, slightly increase |velocity.x|.
// 4) Center line + score SFX: draw a dashed midline; play an audio on score.
// 5) Power-ups: spawn a rectangle; when ball hits it, apply effect (bigger paddle?).
// 6) Pause/Resume: map a key to toggle pause state and skip updates when paused.
// 7) Win screen polish: show a replay countdown, then auto-restart.

// From Nightatthemuseum.md — front matter documents the post's learning narrative
// ---
// layout: post
// title: Night at the Museum
// description: Reflection on presenting our game at the school showcase
// ---

Code Runner Challenge

Hit Run to see a mini-lesson format in code — a self-documenting challenge list printed alongside result output. This is the same pattern used in hacks/pong.md to teach students what to try next.

Lines: 1 Characters: 0
Output
Click "Run" in code control panel to see output ...

Code Highlights

What was learned: Code highlights are annotated snippets in documentation that call out key techniques — like OOP patterns, API calls, or collision logic — and explain why they matter. Highlighting important sections of Pong and the Local Storage Demo helped me clearly communicate the most interesting parts of my work to reviewers.
Evidence: 
// From _projects/local-storage/levels/localStorageDemo.js
// KEY HIGHLIGHT: localStorage persists coin count across page refreshes
// ─────────────────────────────────────────────────────────────────────
const coinsCollected = parseInt(localStorage.getItem('coinsCollected') || '0');
//                              ^ reads stored value, defaults to '0' if absent
localStorage.setItem('coinsCollected', coinsCollected + 1);
//                   ^ key must match exactly or you create a second entry

// KEY HIGHLIGHT: OOP — reaction() is a method override on the Coin object
// ─────────────────────────────────────────────────────────────────────────
reaction: function () {
    if (!this.collected) {
        this.collected = true;      // ← boolean flag prevents double-counting
        const coinsCollected = parseInt(localStorage.getItem('coinsCollected') || '0');
        localStorage.setItem('coinsCollected', coinsCollected + 1);
        // Dispatch event so leaderboard can listen without tight coupling
        document.dispatchEvent(new CustomEvent('coinCollected', { detail: { total: coinsCollected + 1 } }));
    }
}

Code Runner Challenge

Hit Run to see annotated code highlights — the same key snippets that would appear in a portfolio documentation page, with comments explaining WHY each line matters, not just WHAT it does.

Lines: 1 Characters: 0
Output
Click "Run" in code control panel to see output ...

Project Documentation

What was learned: Project documentation means writing about what you built, what you learned, and how you solved problems. This helps you reflect on your progress and share your journey with others. Creating blogs and summaries in this portfolio made it easy to track growth and celebrate achievements.
Evidence: 
// From hacks/pong.md — Student Challenges section documents learning objectives inline
// -----------------------------------------
// Student Challenges (inline TODO checklist)
// -----------------------------------------
// 1) Make it YOUR game: change colors in Config.visuals, dimensions/speeds in Config.
// 2) Add AI: implement simple tracking for right paddle in handleInput. DONE

// From _projects/local-storage/levels/localStorageDemo.js — inline comment documents a bug fix
const image_src_desert = path + "/images/gamify/forest.png";
const image_data_desert = {
    name: 'forest',
    src: image_src_desert,   // ← was image_src_forest (bug fix documented in comment)
    pixels: { height: 580, width: 1038 }
};

Gamerunner — Documentation in Pong

This Pong game is the centerpiece of the documentation mini-lesson — it shows a fully commented, self-explaining game. Every class and method in the source follows JSDoc format. Use W/S and Arrow keys to play.

Challenge

Documented Pong — every class and method has JSDoc comments

Lines: 1 Characters: 0
Game Status: Not Started