← Back to Portfolio

📝 Documentation

Code Comments

Project Evidence Required

JSDoc comments for classes and methods.

Assessment Method

Code review: Comment density >10%

What it is

JavaScript supports single-line comments (// ...) and block comments (/* ... */). JSDoc is a convention using /** ... */ blocks with @param, @returns, and other tags — many editors (VS Code in particular) read these and provide hover-help.

Why it matters

Comments make code teachable. Future-you and future teammates need to understand intent, not just syntax. A function that takes obscure parameters becomes self-documenting with a JSDoc block above it.

How GateGame implements it

The spline() helper has a comment block explaining what the parameters mean and what the return shape is. Each major section of GameLevelMazeSub has a header comment describing what it sets up. Comment density across the file is tracked above the 10% bar to satisfy the CS 111 rubric.

Code Example

// ── Spline barrier helper ─────────────────────────────────────
// points: array of [relX, relY] pairs (0.0-1.0 relative to screen)
// SplineBarrier reads data.splinePoints (pixel coords),
// so we convert here.
function spline(id, points) {
  return {
    id,
    splinePoints: points.map(([px, py]) => ({
      x: Math.round(px * width),
      y: Math.round(py * height)
    })),
    lineWidth: 22,
  };
}

Key Takeaway

Comment the why and the contract, not the what. // adds 1 to x is noise; // points are relative 0-1, we convert to pixels is gold.

---