McTweak Family

The Art of Code Comments

A cyberpunk coding adventure

Episode 1: The Uncommented Mystery

In the neon-drenched streets of Night City, the McTweak Family runs a legendary code review service. When a rookie programmer submits a perfectly functional but completely uncommented website, the team faces an urgent challenge: make the code human-readable before it gets deployed to production.

Scene 1: The Discovery

CodyMcTweak

The Free Assistant

Team, I've been analyzing this rookie developer's HTML. The site works perfectly, but...

There's not a SINGLE COMMENT in the entire codebase! This is going to be a maintenance nightmare when it hits production.

Let me see... oh my. Not even a simple document structure comment. How is anyone supposed to understand the layout intention?

Without proper documentation, future developers will waste hours just trying to understand what's happening.

AllyMcTweak

The Strategic Planner

UNCOMMENTED HTML

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Product Showcase</title>
    <link href="styles.css" rel="stylesheet">
</head>
<body>
    <header>
        <div class="logo"><img src="logo.png" alt="Logo"></div>
        <nav>
            <ul>
                <li><a href="#" class="active">Home</a></li>
                <li><a href="#">Products</a></li>
                <li><a href="#">About</a></li>
                <li><a href="#">Contact</a></li>
            </ul>
        </nav>
        <div class="cart-icon"><span id="cart-count">0</span></div>
    </header>
    
    <main>
        <section class="hero">
            <h1>Cutting-Edge Tech Products</h1>
            <p>Discover innovation that changes how you live.</p>
            <button class="cta-button">Shop Now</button>
        </section>
        
        <section class="products" id="product-grid">
            <div class="product-card" data-id="p1">
                <img src="product1.jpg" alt="Smart Watch">
                <h3>Smart Watch Pro</h3>
                <p class="price">$199.99</p>
                <button class="add-to-cart">Add to Cart</button>
            </div>
            
            <div class="product-card" data-id="p2">
                <img src="product2.jpg" alt="Wireless Headphones">
                <h3>NoiseCancel Headphones</h3>
                <p class="price">$149.99</p>
                <button class="add-to-cart">Add to Cart</button>
            </div>
            
            <div class="product-card" data-id="p3">
                <img src="product3.jpg" alt="Smart Speaker">
                <h3>HomeTalk Speaker</h3>
                <p class="price">$89.99</p>
                <button class="add-to-cart">Add to Cart</button>
            </div>
        </section>
    </main>
    
    <footer>
        <div class="footer-links">
            <div>
                <h4>Shop</h4>
                <ul>
                    <li><a href="#">New Arrivals</a></li>
                    <li><a href="#">Bestsellers</a></li>
                    <li><a href="#">Deals</a></li>
                </ul>
            </div>
            <div>
                <h4>Support</h4>
                <ul>
                    <li><a href="#">Help Center</a></li>
                    <li><a href="#">Warranty</a></li>
                    <li><a href="#">Returns</a></li>
                </ul>
            </div>
        </div>
        <div class="copyright">© 2023 Tech Products Inc. All rights reserved.</div>
    </footer>
    
    <script src="scripts.js"></script>
</body>
</html>

GrumpyMcTweak

The Code Guardian

This is a disaster waiting to happen! Sure, it works today, but what about six months from now?

And where's the associated CSS and JavaScript? I bet they're just as poorly documented! This is exactly why junior developers need proper mentoring!

UNCOMMENTED CSS

body {
    margin: 0;
    font-family: 'Roboto', sans-serif;
    color: #333;
}

header {
    display: flex;
    justify-content: space-between;
    align-items: center;
    padding: 1rem 2rem;
    background-color: #fff;
    box-shadow: 0 2px 10px rgba(0,0,0,0.1);
    position: sticky;
    top: 0;
    z-index: 100;
}

.logo img {
    height: 40px;
}

nav ul {
    display: flex;
    list-style: none;
    gap: 2rem;
}

nav a {
    text-decoration: none;
    color: #333;
    font-weight: 500;
    transition: color 0.3s;
}

nav a.active, nav a:hover {
    color: #2e7eff;
}

.cart-icon {
    position: relative;
    width: 24px;
    height: 24px;
    background: url('cart.svg') no-repeat center;
    cursor: pointer;
}

#cart-count {
    position: absolute;
    top: -8px;
    right: -8px;
    background: #ff4d4d;
    color: white;
    border-radius: 50%;
    width: 18px;
    height: 18px;
    display: flex;
    align-items: center;
    justify-content: center;
    font-size: 12px;
}

.hero {
    background: linear-gradient(135deg, #2e7eff, #7a2eff);
    color: white;
    text-align: center;
    padding: 4rem 2rem;
}

.hero h1 {
    font-size: 2.5rem;
    margin-bottom: 1rem;
}

.cta-button {
    background: #fff;
    color: #2e7eff;
    border: none;
    padding: 0.75rem 2rem;
    font-size: 1rem;
    font-weight: 600;
    border-radius: 4px;
    cursor: pointer;
    transition: transform 0.3s, box-shadow 0.3s;
    margin-top: 1.5rem;
}

.cta-button:hover {
    transform: translateY(-2px);
    box-shadow: 0 5px 15px rgba(0,0,0,0.2);
}

.products {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
    gap: 2rem;
    padding: 2rem;
}

.product-card {
    border: 1px solid #eee;
    border-radius: 8px;
    padding: 1rem;
    transition: transform 0.3s, box-shadow 0.3s;
}

.product-card:hover {
    transform: translateY(-5px);
    box-shadow: 0 10px 20px rgba(0,0,0,0.1);
}

.product-card img {
    width: 100%;
    height: 200px;
    object-fit: cover;
    border-radius: 4px;
}

.product-card h3 {
    margin: 1rem 0 0.5rem;
}

.product-card .price {
    color: #2e7eff;
    font-weight: 600;
    margin-bottom: 1rem;
}

.add-to-cart {
    background: #2e7eff;
    color: white;
    border: none;
    padding: 0.5rem 1rem;
    border-radius: 4px;
    cursor: pointer;
    transition: background 0.3s;
}

.add-to-cart:hover {
    background: #1a60d6;
}

footer {
    background: #333;
    color: white;
    padding: 2rem;
}

.footer-links {
    display: flex;
    justify-content: space-around;
    flex-wrap: wrap;
}

.footer-links div {
    margin-bottom: 1.5rem;
}

.footer-links h4 {
    margin-bottom: 0.75rem;
}

.footer-links ul {
    list-style: none;
    padding: 0;
}

.footer-links a {
    color: #ccc;
    text-decoration: none;
    line-height: 1.8;
}

.footer-links a:hover {
    color: #fff;
}

.copyright {
    text-align: center;
    margin-top: 2rem;
    font-size: 0.875rem;
    color: #ccc;
}

@media (max-width: 768px) {
    .products {
        grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
        padding: 1rem;
    }
    
    nav ul {
        gap: 1rem;
    }
    
    .hero h1 {
        font-size: 2rem;
    }
}

Pfft, this code is garbage! Yeah, it works, but it's like driving without headlights. You'll crash eventually!

Look at this CSS! No comment explaining the responsive breakpoint logic, no section dividers, nothing! What are we supposed to be, psychics?

TrashyMcTweak

The Brutal Critic

UNCOMMENTED JAVASCRIPT

const productData = [
    {
        id: 'p1',
        name: 'Smart Watch Pro',
        price: 199.99,
        image: 'product1.jpg',
        stock: 15
    },
    {
        id: 'p2',
        name: 'NoiseCancel Headphones',
        price: 149.99,
        image: 'product2.jpg',
        stock: 8
    },
    {
        id: 'p3',
        name: 'HomeTalk Speaker',
        price: 89.99,
        image: 'product3.jpg',
        stock: 12
    }
];

let cart = [];
const cartCount = document.getElementById('cart-count');
const productGrid = document.getElementById('product-grid');
const addToCartButtons = document.querySelectorAll('.add-to-cart');

addToCartButtons.forEach(button => {
    button.addEventListener('click', function() {
        const card = this.closest('.product-card');
        const productId = card.dataset.id;
        addToCart(productId);
    });
});

function addToCart(productId) {
    const product = productData.find(p => p.id === productId);
    
    if (!product) return;
    
    const existingItem = cart.find(item => item.id === productId);
    
    if (existingItem) {
        existingItem.quantity += 1;
    } else {
        cart.push({
            id: product.id,
            name: product.name,
            price: product.price,
            quantity: 1
        });
    }
    
    updateCartCount();
    saveCartToStorage();
    showNotification(`Added ${product.name} to cart!`);
}

function updateCartCount() {
    const totalItems = cart.reduce((total, item) => total + item.quantity, 0);
    cartCount.textContent = totalItems;
}

function saveCartToStorage() {
    localStorage.setItem('shopping-cart', JSON.stringify(cart));
}

function loadCartFromStorage() {
    const savedCart = localStorage.getItem('shopping-cart');
    if (savedCart) {
        cart = JSON.parse(savedCart);
        updateCartCount();
    }
}

function showNotification(message) {
    const notification = document.createElement('div');
    notification.className = 'notification';
    notification.textContent = message;
    
    document.body.appendChild(notification);
    
    setTimeout(() => {
        notification.classList.add('show');
    }, 10);
    
    setTimeout(() => {
        notification.classList.remove('show');
        setTimeout(() => {
            document.body.removeChild(notification);
        }, 300);
    }, 3000);
}

document.addEventListener('DOMContentLoaded', function() {
    loadCartFromStorage();
});

Scene 2: The Plan of Action

FattyMcTweak

The Powerhouse

Alright, settle down everyone. We can fix this. Here's our plan of attack:

Start with header comments explaining each file's purpose
Add section comments dividing major components
Document tricky CSS selectors and JS functions
Explain any non-obvious logic or complex features
Ensure consistent comment formatting throughout

Remember the key principles of good code commenting:

Comments should explain WHY, not just WHAT (the code itself shows what it does)
Keep comments updated with code changes
Use consistent formatting for readability
Avoid unnecessary comments that state the obvious
Comment complex algorithms and business logic thoroughly

GarbageMcTweak

The Master Coder

Scene 3: Commenting the HTML

CodyMcTweak

The Free Assistant

Let's start with the HTML file. We'll add a header comment explaining the overall purpose, then add section comments for major parts of the page structure.

This will make it much easier to navigate the document structure.

IMPROVED HTML WITH COMMENTS

<!--
    Product Showcase Website
    
    This is the main HTML structure for our e-commerce product showcase website.
    It features a responsive design with a navigation header, product grid,
    and a shopping cart functionality.
    
    Created: June 2023
    Author: Tech Team
    Last Updated: September 2023
-->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Product Showcase</title>
    <link href="styles.css" rel="stylesheet">
</head>
<body>
    <!-- 
        Header Section
        Contains logo, navigation menu, and shopping cart icon with item count
    -->
    <header>
        <div class="logo"><img src="logo.png" alt="Logo"></div>
        <nav>
            <ul>
                <li><a href="#" class="active">Home</a></li>
                <li><a href="#">Products</a></li>
                <li><a href="#">About</a></li>
                <li><a href="#">Contact</a></li>
            </ul>
        </nav>
        <!-- Cart icon with dynamic count indicator updated by JavaScript -->
        <div class="cart-icon"><span id="cart-count">0</span></div>
    </header>
    
    <main>
        <!-- 
            Hero Section
            Main promotional area with call-to-action button 
        -->
        <section class="hero">
            <h1>Cutting-Edge Tech Products</h1>
            <p>Discover innovation that changes how you live.</p>
            <button class="cta-button">Shop Now</button>
        </section>
        
        <!-- 
            Products Grid
            Dynamic product display area populated with product cards
            Each card has data-id attribute used by JS for cart operations
        -->
        <section class="products" id="product-grid">
            <div class="product-card" data-id="p1">
                <img src="product1.jpg" alt="Smart Watch">
                <h3>Smart Watch Pro</h3>
                <p class="price">$199.99</p>
                <button class="add-to-cart">Add to Cart</button>
            </div>
            
            <div class="product-card" data-id="p2">
                <img src="product2.jpg" alt="Wireless Headphones">
                <h3>NoiseCancel Headphones</h3>
                <p class="price">$149.99</p>
                <button class="add-to-cart">Add to Cart</button>
            </div>
            
            <div class="product-card" data-id="p3">
                <img src="product3.jpg" alt="Smart Speaker">
                <h3>HomeTalk Speaker</h3>
                <p class="price">$89.99</p>
                <button class="add-to-cart">Add to Cart</button>
            </div>
        </section>
    </main>
    
    <!-- 
        Footer Section
        Contains site navigation links and copyright information
    -->
    <footer>
        <div class="footer-links">
            <div>
                <h4>Shop</h4>
                <ul>
                    <li><a href="#">New Arrivals</a></li>
                    <li><a href="#">Bestsellers</a></li>
                    <li><a href="#">Deals</a></li>
                </ul>
            </div>
            <div>
                <h4>Support</h4>
                <ul>
                    <li><a href="#">Help Center</a></li>
                    <li><a href="#">Warranty</a></li>
                    <li><a href="#">Returns</a></li>
                </ul>
            </div>
        </div>
        <div class="copyright">© 2023 Tech Products Inc. All rights reserved.</div>
    </footer>
    
    <!-- 
        Main JavaScript file handling cart functionality and user interactions
        See scripts.js for documentation
    -->
    <script src="scripts.js"></script>
</body>
</html>

That's so much better! Now anyone can quickly understand the structure of the page and how the different sections relate to each other.

The comments about the data-id attributes and the cart-icon are particularly helpful since they explain the connection to JavaScript functionality.

AllyMcTweak

The Strategic Planner

Scene 4: Commenting the CSS

GrumpyMcTweak

The Code Guardian

Now let's tackle the CSS. We need clear section dividers and explanations for any complex styling decisions.

The media query is particularly important to document, as future developers need to understand our breakpoint choices!

IMPROVED CSS WITH COMMENTS

/*
 * Product Showcase Website Styles
 * 
 * This stylesheet contains all styles for the product showcase website,
 * organized by page section (header, hero, products, footer).
 * The design uses a responsive layout with breakpoints at 768px.
 *
 * Color Scheme:
 * - Primary: #2e7eff (blue)
 * - Secondary: #7a2eff (purple)
 * - Accent: #ff4d4d (red)
 * - Text: #333 (dark gray)
 */

/* ---------- Base Styles ---------- */
body {
    margin: 0;
    font-family: 'Roboto', sans-serif;
    color: #333;
}

/* ---------- Header Styles ---------- */
header {
    display: flex;
    justify-content: space-between;
    align-items: center;
    padding: 1rem 2rem;
    background-color: #fff;
    box-shadow: 0 2px 10px rgba(0,0,0,0.1);
    position: sticky;  /* Keeps header visible when scrolling */
    top: 0;
    z-index: 100;     /* Ensures header stays above other content */
}

.logo img {
    height: 40px;
}

/* Navigation menu */
nav ul {
    display: flex;
    list-style: none;
    gap: 2rem;
}

nav a {
    text-decoration: none;
    color: #333;
    font-weight: 500;
    transition: color 0.3s;
}

nav a.active, nav a:hover {
    color: #2e7eff;
}

/* Shopping cart icon with counter badge */
.cart-icon {
    position: relative;
    width: 24px;
    height: 24px;
    background: url('cart.svg') no-repeat center;
    cursor: pointer;
}

#cart-count {
    position: absolute;
    top: -8px;
    right: -8px;
    background: #ff4d4d;  /* Red notification badge */
    color: white;
    border-radius: 50%;
    width: 18px;
    height: 18px;
    display: flex;
    align-items: center;
    justify-content: center;
    font-size: 12px;
}

/* ---------- Hero Section ---------- */
.hero {
    background: linear-gradient(135deg, #2e7eff, #7a2eff);
    color: white;
    text-align: center;
    padding: 4rem 2rem;
}

.hero h1 {
    font-size: 2.5rem;
    margin-bottom: 1rem;
}

.cta-button {
    background: #fff;
    color: #2e7eff;
    border: none;
    padding: 0.75rem 2rem;
    font-size: 1rem;
    font-weight: 600;
    border-radius: 4px;
    cursor: pointer;
    transition: transform 0.3s, box-shadow 0.3s;
    margin-top: 1.5rem;
}

.cta-button:hover {
    transform: translateY(-2px);  /* Subtle lift effect on hover */
    box-shadow: 0 5px 15px rgba(0,0,0,0.2);
}

/* ---------- Product Grid Section ---------- */
.products {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
    gap: 2rem;
    padding: 2rem;
}

/* Individual product cards */
.product-card {
    border: 1px solid #eee;
    border-radius: 8px;
    padding: 1rem;
    transition: transform 0.3s, box-shadow 0.3s;
}

.product-card:hover {
    transform: translateY(-5px);  /* Card rises on hover for interactive feel */
    box-shadow: 0 10px 20px rgba(0,0,0,0.1);
}

.product-card img {
    width: 100%;
    height: 200px;
    object-fit: cover;  /* Maintains aspect ratio while filling space */
    border-radius: 4px;
}

.product-card h3 {
    margin: 1rem 0 0.5rem;
}

.product-card .price {
    color: #2e7eff;
    font-weight: 600;
    margin-bottom: 1rem;
}

.add-to-cart {
    background: #2e7eff;
    color: white;
    border: none;
    padding: 0.5rem 1rem;
    border-radius: 4px;
    cursor: pointer;
    transition: background 0.3s;
}

.add-to-cart:hover {
    background: #1a60d6;
}

/* ---------- Footer Section ---------- */
footer {
    background: #333;
    color: white;
    padding: 2rem;
}

.footer-links {
    display: flex;
    justify-content: space-around;
    flex-wrap: wrap;  /* Allows proper stacking on small screens */
}

.footer-links div {
    margin-bottom: 1.5rem;
}

.footer-links h4 {
    margin-bottom: 0.75rem;
}

.footer-links ul {
    list-style: none;
    padding: 0;
}

.footer-links a {
    color: #ccc;
    text-decoration: none;
    line-height: 1.8;
}

.footer-links a:hover {
    color: #fff;
}

.copyright {
    text-align: center;
    margin-top: 2rem;
    font-size: 0.875rem;
    color: #ccc;
}

/* ---------- Responsive Adjustments ---------- */
@media (max-width: 768px) {
    /* Adjust product grid for smaller screens */
    .products {
        grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
        padding: 1rem;
    }
    
    /* Reduce navigation spacing */
    nav ul {
        gap: 1rem;
    }
    
    /* Smaller hero text */
    .hero h1 {
        font-size: 2rem;
    }
}

OK, OK, that's actually not terrible now. I especially like how the color scheme is documented right at the top - makes it easier to maintain consistent colors.

The section dividers make it much easier to find specific parts of the stylesheet when you need to make changes. But we better not skimp on the JavaScript comments!

TrashyMcTweak

The Brutal Critic

Scene 5: Commenting the JavaScript

GarbageMcTweak

The Master Coder

The JavaScript code needs the most thorough documentation of all. Logic needs to be clearly explained, especially the local storage functionality and cart operations.

Let's use JSDoc format for function comments to enable better IDE integration and provide clear parameter documentation.

IMPROVED JAVASCRIPT WITH COMMENTS

/**
 * Product Showcase Website - Shopping Cart Module
 * 
 * This script handles all shopping cart functionality including:
 * - Adding products to cart
 * - Updating cart item count
 * - Saving/loading cart state from local storage
 * - Displaying notification messages to the user
 * 
 * Dependencies: None (vanilla JavaScript)
 * Author: Tech Team
 * Last Updated: September 2023
 */

/**
 * Product data array containing all available products
 * Used as the data source for the shopping cart operations
 */
const productData = [
    {
        id: 'p1',
        name: 'Smart Watch Pro',
        price: 199.99,
        image: 'product1.jpg',
        stock: 15
    },
    {
        id: 'p2',
        name: 'NoiseCancel Headphones',
        price: 149.99,
        image: 'product2.jpg',
        stock: 8
    },
    {
        id: 'p3',
        name: 'HomeTalk Speaker',
        price: 89.99,
        image: 'product3.jpg',
        stock: 12
    }
];

// Shopping cart state and DOM element references
let cart = [];
const cartCount = document.getElementById('cart-count');
const productGrid = document.getElementById('product-grid');
const addToCartButtons = document.querySelectorAll('.add-to-cart');

// Initialize event listeners for all Add to Cart buttons
addToCartButtons.forEach(button => {
    button.addEventListener('click', function() {
        const card = this.closest('.product-card');
        const productId = card.dataset.id;
        addToCart(productId);
    });
});

/**
 * Adds a product to the shopping cart or increases its quantity if already present
 * Updates the UI, saves to local storage, and shows a notification to the user
 * 
 * @param {string} productId - The unique identifier of the product to add
 */
function addToCart(productId) {
    const product = productData.find(p => p.id === productId);
    
    // Guard clause: exit if product not found
    if (!product) return;
    
    // Check if item is already in cart
    const existingItem = cart.find(item => item.id === productId);
    
    if (existingItem) {
        // Increment quantity if already in cart
        existingItem.quantity += 1;
    } else {
        // Add new item to cart with quantity of 1
        cart.push({
            id: product.id,
            name: product.name,
            price: product.price,
            quantity: 1
        });
    }
    
    // Update UI and persist changes
    updateCartCount();
    saveCartToStorage();
    showNotification(`Added ${product.name} to cart!`);
}

/**
 * Updates the cart count indicator in the header
 * Calculates the total number of items across all products
 */
function updateCartCount() {
    // Calculate sum of quantities for all cart items
    const totalItems = cart.reduce((total, item) => total + item.quantity, 0);
    cartCount.textContent = totalItems;
}

/**
 * Saves the current cart state to browser's local storage
 * This persists the cart between page reloads
 */
function saveCartToStorage() {
    localStorage.setItem('shopping-cart', JSON.stringify(cart));
}

/**
 * Loads the saved cart state from browser's local storage
 * Called on page load to restore previous shopping session
 */
function loadCartFromStorage() {
    const savedCart = localStorage.getItem('shopping-cart');
    if (savedCart) {
        cart = JSON.parse(savedCart);
        updateCartCount();
    }
}

/**
 * Shows a temporary notification message to the user
 * Creates a notification element, displays it, then removes it after a delay
 * 
 * @param {string} message - The message to display to the user
 */
function showNotification(message) {
    const notification = document.createElement('div');
    notification.className = 'notification';
    notification.textContent = message;
    
    // Add to DOM
    document.body.appendChild(notification);
    
    // Small delay before showing (allows CSS transitions to work properly)
    setTimeout(() => {
        notification.classList.add('show');
    }, 10);
    
    // Remove notification after 3 seconds
    setTimeout(() => {
        notification.classList.remove('show');
        setTimeout(() => {
            document.body.removeChild(notification);
        }, 300); // Wait for fade-out animation to complete
    }, 3000);
}

// Initialize cart when the DOM is fully loaded
document.addEventListener('DOMContentLoaded', function() {
    loadCartFromStorage();
});

FattyMcTweak

The Powerhouse

Perfect! The JSDoc format for function comments is exactly what we needed. Future developers will understand:

What each function does
What parameters it expects
How the local storage persistence works
The notification system's timing logic

These comments don't just repeat what the code does - they explain the WHY and provide context.

Scene 6: Mission Accomplished

We've successfully upgraded all three files with proper comments. Our junior developer's code is now:

Clearly documented with header comments
Divided into logical sections
Explained with useful context, not just redundant notes
Enhanced with JSDoc format for function documentation
Ready for collaborative development!

CodyMcTweak

The Free Assistant

GrumpyMcTweak

The Code Guardian

I still think we should rewrite the whole thing from scratch, but... I guess this is acceptable. At least I won't get a migraine trying to figure out what this code does six months from now.

Just make sure the rookie learns from this. Comments aren't optional; they're essential!

The McTweak Guide to Code Comments

HTML Commenting Best Practices

DO

Add a file header explaining the document's purpose
Use section comments to organize content
Document connections to JavaScript functionality
Explain non-standard attribute usage

DON'T

Comment every single HTML element
Add comments that simply repeat tag names
Leave commented-out code without explanation
Use comments for visual separation only

CSS Commenting Best Practices

DO

Document your color scheme and variables
Use section dividers for organization
Explain complex selectors or specificity decisions
Document responsive breakpoints and logic

DON'T

Add redundant comments to simple properties
Leave outdated comments when updating styles
Use vague comments like "fixes IE bug"
Include commented-out code without explanation

JavaScript Commenting Best Practices

DO

Use JSDoc format for function documentation
Document parameters and return values
Explain complex logic and business rules
Add context to non-obvious code solutions
Document any assumptions or edge cases

DON'T

Write comments that just repeat the code
Leave commented-out functions without explanation
Add TODOs without actionable information
Leave debug console.log statements commented-out
Forget to update comments when code changes

Remember: Good comments explain WHY, not just WHAT.

Write code today that your future self will thank you for!