Stop Writing Useless JavaScript Comments - Here's What Actually Helps Your Team

Master JavaScript comments that save debugging time. Learn JSDoc, conditional comments, and team-friendly practices in 20 minutes.
·
10 min read
·
Mark
·
JavaScript Java

I spent two years writing terrible comments that made my code harder to read, not easier.

Then I joined a team where my "clever" comments got me called into a code review meeting. That was embarrassing. Here's what I learned about writing JavaScript comments that actually help your team ship faster.

What you'll master: Professional comment techniques that save debugging time
Time needed: 20 minutes of reading, lifetime of better code
Difficulty: Easy wins with some advanced tricks

You'll stop writing comments that explain what the code does and start writing comments that explain why it exists.

Why I Had to Learn This the Hard Way

My first real JavaScript job was at a startup with zero code standards. I wrote comments like this:

// increment counter by 1
counter++; 

// loop through array
for (let i = 0; i < users.length; i++) {
    // do something
}

My setup:

  • React codebase with 15 developers
  • No comment standards or guidelines
  • Features shipped every 2 weeks
  • Constant context switching between projects

What broke:

  • New developers spent days understanding my "documented" code
  • Comments became outdated within weeks
  • Code reviews focused on comment quality, not logic
  • I wasted hours explaining code that should speak for itself

The 4 Types of Comments That Actually Matter

The problem: Most developers write comments that duplicate what the code already shows.

My solution: Four specific comment types that add real value.

Time this saves: 30 minutes per code review, hours of debugging later.

Type 1: Intent Comments (Why, Not What)

Bad comments explain what happens. Good comments explain why it happens.

// BAD: Explains what (obvious from code)
// Set timeout to 3000 milliseconds
setTimeout(callback, 3000);

// GOOD: Explains why (not obvious from code)
// Instagram API rate limit resets every 3 seconds
setTimeout(callback, 3000);

What this does: Gives future you the context you'll forget in 2 weeks. Expected output: Code reviews focus on logic, not explanation requests.

Personal tip: "If you can delete the comment and still understand the code, delete it. If deleting it removes important context, keep it."

Type 2: Warning Comments (Save Others Pain)

Share your debugging discoveries before someone else hits the same wall.

// CRITICAL: Don't use async/await here
// React 16 batch updates break with promises in event handlers  
const handleClick = (e) => {
    // Use .then() instead - learned this after 3 hours debugging
    fetchUserData(userId).then(updateState);
};

// Performance warning: This runs on every scroll event
// Debounce to 16ms or browser will lag on slow devices
const handleScroll = debounce((e) => {
    updateScrollPosition(e.target.scrollTop);
}, 16);

What this does: Prevents your team from repeating your mistakes. Expected output: Fewer "why did you do it this way?" Slack messages.

Personal tip: "I add warning comments immediately after fixing tricky bugs. The pain is fresh and the context is clear."

Type 3: Business Logic Comments (Domain Knowledge)

Some code needs business context that developers can't guess from variable names.

// Stripe requires amount in cents, but our API returns dollars
const chargeAmount = priceInDollars * 100;

// EU users must explicitly consent to analytics (GDPR)
// US users are opt-out by default  
const trackingEnabled = user.region === 'EU' ? user.hasConsented : true;

// Legacy customers (pre-2023) get grandfathered pricing
// New pricing starts 40% higher but includes premium features
const monthlyRate = customer.signupDate < '2023-01-01' ? 29.99 : 49.99;

What this does: Documents business rules that aren't obvious from code structure. Expected output: Product managers can read your code and understand the logic.

Personal tip: "Business logic comments are goldmines during onboarding. New developers understand the 'why' behind weird-looking code."

Type 4: Complex Algorithm Comments (Mental Models)

When you implement something non-obvious, leave breadcrumbs for the next person.

// Binary search implementation
// Returns index of target value, -1 if not found
// Time: O(log n), Space: O(1)
function binarySearch(arr, target) {
    let left = 0;
    let right = arr.length - 1;
    
    while (left <= right) {
        // Avoid integer overflow with (left + right) / 2
        const mid = Math.floor(left + (right - left) / 2);
        
        if (arr[mid] === target) return mid;
        if (arr[mid] < target) {
            left = mid + 1;  // Target is in right half
        } else {
            right = mid - 1; // Target is in left half  
        }
    }
    return -1;
}

What this does: Explains the approach and key insights. Expected output: Other developers can modify the algorithm confidently.

Personal tip: "I comment complex algorithms like I'm explaining them to myself in 6 months. Because I am."

JSDoc: Professional Documentation That Pays Off

The problem: Your functions need documentation but you don't want to maintain separate docs.

My solution: JSDoc comments that live with your code and generate documentation automatically.

Time this saves: Hours of writing separate documentation, instant IDE help for your team.

Basic JSDoc Structure

/**
 * Formats user data for the profile display component
 * 
 * @param {Object} user - Raw user object from API
 * @param {string} user.name - Full name 
 * @param {string} user.email - Email address
 * @param {boolean} [user.isActive=true] - Account status (optional)
 * @returns {Object} Formatted user object with display properties
 * @throws {Error} When user object is missing required fields
 * 
 * @example
 * const formatted = formatUserProfile({
 *   name: 'Sarah Chen',
 *   email: 'sarah@example.com'
 * });
 * // Returns: { displayName: 'Sarah Chen', avatar: 'SC', ... }
 */
function formatUserProfile(user) {
    if (!user.name || !user.email) {
        throw new Error('User must have name and email');
    }
    
    return {
        displayName: user.name,
        avatar: user.name.split(' ').map(n => n[0]).join(''),
        status: user.isActive ?? true
    };
}

What this does: Your IDE shows parameter types and examples when teammates use your function. Expected output: Zero "how do I use this function?" questions in code reviews.

Personal tip: "The @example tag is magic. It shows up in VS Code tooltips and prevents integration mistakes."

Advanced JSDoc for Complex Types

/**
 * @typedef {Object} APIResponse
 * @property {boolean} success - Request status
 * @property {string} message - Human readable message
 * @property {Object} data - Response payload
 */

/**
 * @typedef {Object} UserPreferences  
 * @property {'light'|'dark'|'auto'} theme - UI theme setting
 * @property {number} timeout - Session timeout in minutes
 * @property {string[]} notifications - Enabled notification types
 */

/**
 * Updates user preferences with validation and persistence
 * 
 * @async
 * @param {string} userId - Unique user identifier
 * @param {Partial<UserPreferences>} preferences - Preferences to update
 * @returns {Promise<APIResponse>} Update result with success status
 * 
 * @example
 * await updateUserPreferences('user123', { 
 *   theme: 'dark',
 *   timeout: 120 
 * });
 */
async function updateUserPreferences(userId, preferences) {
    // Implementation here
}

What this does: Creates reusable type definitions that work across your entire codebase. Expected output: VS Code autocomplete knows your custom types and catches type errors.

Personal tip: "I define complex types once in JSDoc, then reference them everywhere. It's like TypeScript lite."

Conditional Comments: Debug Like a Pro

The problem: You need debugging code that doesn't ship to production.

My solution: Conditional comments that build tools can remove automatically.

Time this saves: No manual cleanup of debug code before deployment.

Development-Only Comments

const processUserData = (users) => {
    /* DEBUG_START */
    console.log('Processing', users.length, 'users');
    console.time('processUserData');
    /* DEBUG_END */
    
    const results = users.map(transformUser);
    
    /* DEBUG_START */
    console.timeEnd('processUserData');
    console.log('Results:', results.length, 'processed');
    /* DEBUG_END */
    
    return results;
};

// Feature flag comments for experimental code
/* FEATURE_FLAG: new-dashboard */
const renderNewDashboard = () => {
    return <NewDashboardComponent />;
};
/* END_FEATURE_FLAG: new-dashboard */

What this does: Webpack or other build tools strip these sections in production builds. Expected output: Clean production code with zero debug statements.

Personal tip: "I use DEBUG_START/END for temporary logging and FEATURE_FLAG for A/B testing code. Build tools handle the cleanup."

Comment Patterns That Scale with Teams

The problem: Your comment style works for you but confuses teammates.

My solution: Consistent patterns everyone can follow.

Time this saves: 50% less time explaining code in reviews.

TODO Comments with Accountability

// TODO(sarah, 2025-09-15): Replace with GraphQL query when API v3 ships
// Current REST endpoint deprecated in Q4 2025
const fetchUserData = async (userId) => {
    // Legacy implementation until migration complete
    return fetch(`/api/v2/users/${userId}`);
};

// FIXME(team-backend): Database query slow with >1000 users  
// See performance ticket: JIRA-1234
// Temporary pagination added below
const getAllUsers = () => {
    return User.find().limit(100); // Band-aid fix
};

What this does: Creates trackable technical debt with clear ownership. Expected output: TODOs don't get forgotten and FIXMEs get prioritized properly.

Personal tip: "I include my name and date on every TODO. It makes me accountable and helps teammates know who to ask about it."

Code Review Comments

// Code review feedback from @mike:
// "This handles the happy path but what about network failures?"
// Added retry logic below to address edge cases
const saveUserProfile = async (data) => {
    try {
        return await api.updateProfile(data);
    } catch (error) {
        // Retry once on network errors (addresses code review feedback)
        if (error.code === 'NETWORK_ERROR') {
            await delay(1000);
            return api.updateProfile(data);
        }
        throw error;
    }
};

What this does: Shows you addressed feedback and explains the solution context. Expected output: Reviewers see their feedback was implemented thoughtfully.

Personal tip: "When I implement code review feedback, I comment why the change was needed. It shows I understood the concern."

What Not to Comment (Avoid These Mistakes)

Never Document These Things

// BAD: Obvious from code
// Create new variable called name
const name = user.firstName + ' ' + user.lastName;

// BAD: Restates the code
// If user is admin, show admin panel  
if (user.role === 'admin') {
    showAdminPanel();
}

// BAD: Outdated information
// This returns a string (actually returns a Promise now)
async function getUserName() {
    return fetch('/api/user').then(r => r.json());
}

What to do instead: Let the code speak for itself. Add comments only when the context isn't clear.

Don't Comment Bad Code, Fix It

// BAD: Commenting around confusing code
// This is confusing but it works, don't change it
const x = (a, b, c) => a ? (b || c) : c;

// GOOD: Rewrite the code to be self-documenting  
const selectActiveValue = (isActive, primaryValue, fallbackValue) => {
    return isActive ? (primaryValue || fallbackValue) : fallbackValue;
};

Personal tip: "If I'm writing a comment to explain confusing code, I rewrite the code instead. Clear code rarely needs comments."

Advanced Comment Techniques

Documentation Generation

Set up automatic documentation with JSDoc:

# Install JSDoc globally
npm install -g jsdoc

# Generate docs from your comments
jsdoc src/ -d docs/ -R README.md

What this does: Creates professional documentation website from your JSDoc comments. Expected output: Always up-to-date docs that match your actual code.

VS Code Comment Extensions

/**
 * @fileoverview User authentication utilities
 * @author Sarah Chen <sarah@company.com>
 * @since 2025-01-15
 * @version 1.2.0
 */

// NOTE: This approach was chosen over JWT because...
// WARNING: Changing this will break mobile app authentication
// HACK: Temporary fix until we migrate to OAuth 2.0  
// REVIEW: Should we extract this to a separate service?

What this does: Extensions highlight different comment types with colors and icons. Expected output: Visual scanning of code context at a glance.

Personal tip: "I use the Better Comments VS Code extension. It color-codes NOTE, WARNING, HACK, and REVIEW comments automatically."

What You Just Built

You now write comments that add real value instead of restating obvious code. Your team can understand your intent, avoid your mistakes, and maintain your code confidently.

Key Takeaways (Save These)

  • Intent over implementation: Explain why, not what - the code shows what
  • Share your pain: Warning comments save teammates hours of debugging
  • JSDoc pays off: Professional documentation that lives with your code and updates automatically
  • Make TODOs trackable: Include your name and date so technical debt gets addressed

Your Next Steps

Pick one:

  • Beginner: Review your last 3 functions and add intent comments where needed
  • Intermediate: Set up JSDoc documentation generation for your current project
  • Advanced: Create team comment standards document with these patterns

Tools I Actually Use

  • Better Comments (VS Code): Color-codes different comment types automatically
  • JSDoc: Professional documentation generation from code comments
  • ESLint: Enforces comment formatting and catches outdated TODOs
  • Prettier: Consistent comment formatting across the entire team