When to Use Comments Instead of Full Game Dev Docs

Posted by Gemma Ellison

July 29, 2025

Comments vs. Docs: A Solo Game Dev’s Dilemma

Let’s be honest, we’ve all been there. Staring blankly at code we wrote three months ago, wondering, “What was I thinking?” Game development is a marathon, not a sprint. How do you keep your sanity, avoid re-inventing the wheel, and remember your brilliant (or not-so-brilliant) ideas? That’s where documentation comes in, but the trick is finding the right balance.

Day 1: Enemy AI Bug Hunt

Alright, day one. I’m tracking down a weird bug in the enemy AI. They’re supposed to patrol, but sometimes they just… stop.

// TO-DO: Investigate why enemies occasionally freeze during patrol. Possible navigation mesh issue?

That’s the only comment I have in the relevant script. Helpful? Not really. I remember vaguely thinking about the navigation mesh, but no details.

Pitfall #1: Vague Comments. “Fix bug later” is NOT helpful for future you.

Solution: Be specific, even in comments. “Enemy freezes at patrol point 3. Suspect NavMeshAgent.remainingDistance not updating correctly.”

Day 2: Adding a New Weapon

Today, I’m implementing a new weapon: a plasma rifle. I’m tempted to just dive in, but I know better (sort of). I need a plan.

Instead of firing up the IDE, I jot down a quick outline in my game dev journal:

Weapon Type: Hitscan
Damage: 25
Range: 50 meters
Special: Overheats if fired rapidly

This isn’t code, but it’s crucial. This high-level design will inform my coding.

Pitfall #2: Coding Without a Plan. Jumping straight into code without outlining your design leads to spaghetti code and feature creep.

Day 3: Implementing the Plasma Rifle

Okay, time to code. I’m focusing on the weapon’s firing mechanism.

void FirePlasma() {
    // Raycast to detect hits
    RaycastHit hit;
    if (Physics.Raycast(transform.position, transform.forward, out hit, range)) {
        // Apply damage to target
        IDamageable target = hit.collider.GetComponent<IDamageable>();
        if (target != null) {
            target.TakeDamage(damage);
        }
    }
    // Overheat the weapon
    currentHeat += heatPerShot;
}

Good enough for now. But what about those currentHeat and heatPerShot variables?

public float currentHeat; // Current heat level of the weapon.
public float heatPerShot = 5f; // Heat added per shot.

That’s better. Simple comments explaining the variables.

Pitfall #3: Under-Commenting Variables. Assume your future self has forgotten everything.

Solution: Comment every public variable and any private variable with a non-obvious purpose.

Day 4: Overheating Mechanic

Now, for the overheating mechanic. This is getting complex.

// TODO: Implement weapon overheating. Prevent firing if currentHeat >= maxHeat.

That TODO is insufficient. I need more detail.

I add a function-level comment block:

/// <summary>
/// Handles the weapon's overheating mechanic. Prevents firing if the weapon is overheated.
/// Gradually cools down the weapon when not firing.
/// </summary>
void HandleOverheating() {
    // ...code here...
}

This is better than a simple "// TODO". It describes the function’s purpose.

Day 5: Refactoring and Documentation

The plasma rifle is working, but the code is messy. Time for refactoring. As I rewrite sections, I realize my in-code comments aren’t enough. I need a broader document explaining the weapon system’s architecture.

I start a separate document (a markdown file, for example) and outline:

Weapon System Overview: High-level explanation of how weapons work.
Plasma Rifle Specifics: Damage, range, overheating.
Extensibility: How to add new weapons easily.

This document is for the long term. It’s for understanding the why, not just the how.

Pitfall #4: Over-Documenting Too Early. Don’t write extensive documentation before your core mechanics are stable. Focus on comments during rapid prototyping.

Solution: Prioritize in-code comments early on. Defer detailed documentation until the system stabilizes.

Day 6: Testing and Polish

Today is all about testing. I found a weird bug: the overheating sound keeps playing even after the weapon has cooled down.

I fix it, and add a comment:

void HandleOverheating() {
    // ...code here...

    // Fix: Stop the overheating sound when currentHeat reaches 0.
    if (currentHeat <= 0 && overheatingSound.isPlaying) {
        overheatingSound.Stop();
    }
}

This comment explains why I added that specific code. It’s invaluable for future debugging.

Pitfall #5: Not Documenting Bug Fixes. When you fix a bug, explain why the fix was necessary.

Solution: Always comment bug fixes, explaining the original problem and your solution.

The Right Balance

The key is finding the balance between in-code comments and dedicated documentation. Comments are for immediate understanding, while documentation is for long-term maintainability and high-level design. As a solo dev, your documentation isn’t just for others — it’s for future you.

Day 7: Reflecting and Planning

Looking back at the week, I realize tracking my progress in a game dev journal has been incredibly helpful. It’s not just about documenting the code, it’s about documenting the process. My journal entries captured design decisions, bug fixes, and even moments of frustration.

Keeping a game development log is a great habit to build. It helps you stay organized, track your progress, and learn from your mistakes. There are many game dev journal tools out there. And hey, if you are looking to level up your game dev tracking, consider checking out our journaling tool to track and optimize your game dev habits: Documenting your game’s progress.