Why Comments Are Often Unnecessary in Code 🤔

You’ve probably been told: “Comment your code!” But here’s the secret: good code explains itself. Comments are rarely needed, and they often do more harm than good.

🎯 The Core Idea

Code should be understandable WITHOUT comments. If you need a comment to explain what the code does — the code is written wrong!

❌ Bad Example (with comments)

# Calculate the area of a rectangle
a = 5
b = 10
s = a * b  # multiply the sides
print(s)   # print the result

Hard to read. You have to look at both the code AND the comments.

✅ Good Example (without comments)

width = 5
height = 10
rectangle_area = width * height
print(rectangle_area)

Easy to read! The variable names explain everything. No comments needed.

🚫 5 Types of HARMFUL Comments

1. “Obvious” Comments

# ❌ BAD: The comment just repeats the code
age = age + 1  # increment age by 1

# ✅ GOOD: Just a clear variable name
user_age += 1

2. “Stale” Comments

# ❌ BAD: The comment is lying! (temperature is already in Celsius)
temperature_celsius = 25  # temperature in Fahrenheit

# ✅ GOOD: No comment needed
temperature_celsius = 25

The problem: Code gets updated, but comments are forgotten. They start to lie!

3. “Apologetic” Comments

# ❌ BAD: You're admitting the code is bad
# TODO: rewrite this hack
# FIXME: there's a bug, but it works
x = calculate_weird_stuff()  # no idea how this works

# ✅ GOOD: Just fix the code instead of commenting!
discount_amount = calculate_discount(price, promo_code)

4. “Commented-out Code”

# ❌ BAD: Old code clutters the new code
def launch_rocket():
    # fuel = 100
    # if fuel > 50:
    #     print("OK")
    fuel_level = get_fuel_tank_percentage()
    if fuel_level >= 75:
        print("🚀 Ready for launch!")

The problem: It’s unclear why it’s there! Should you use it? Delete it? Why was it left?

The fix: Delete old code without fear. You have Git — you can always get it back.

5. “Noise” Comments

# ❌ BAD: A comment on every line
# Greeting function
def greet():
    # Create the name variable
    name = input("What's your name? ")
    # Print the greeting
    print(f"Hello, {name}!")

# ✅ GOOD: Code reads like prose
def greet_user():
    user_name = input("What's your name? ")
    print(f"Hello, {user_name}!")

✅ When Comments ARE Needed

1. Explaining “why”, not “what”

# Using sleep to give the system time to load
# (the documentation requires a minimum of 2 seconds)
time.sleep(2)

# Multiplying by 1.2 because the library returns the value in kilobytes
# but we need to account for overhead (+20%)
file_size_with_overhead = raw_size * 1.2

2. Complex Math or Algorithms

# Heron's formula for triangle area: S = √(p(p-a)(p-b)(p-c))
# where p is the semi-perimeter
semi_perimeter = (a + b + c) / 2
area = (semi_perimeter * (semi_perimeter - a) * (semi_perimeter - b) * (semi_perimeter - c)) ** 0.5

3. Important Warnings

# WARNING: This method sends REAL money!
# Only call after user confirmation
def process_payment(amount):
    ...

4. TODOs for Yourself

# TODO: Add validation for negative numbers
def calculate_discount(price):
    return price * 0.9

🎓 Clean Code Rules

Rule 1: Descriptive Names

# ❌ Bad
t = 25

# ✅ Good
temperature_celsius = 25

Rule 2: Short Functions

# ❌ Bad: A 50-line function with comments
def do_everything():
    # ... 50 lines of code ...

# ✅ Good: Break it into small functions with clear names
def validate_input():
    ...

def calculate_result():
    ...

def display_output():
    ...

Rule 3: Single Level of Abstraction

# ❌ Bad: Details and high-level logic are mixed
def launch():
    fuel = 100
    if fuel > 50:  # fuel check
        time.sleep(1)  # countdown timer
        print("Launch!")

# ✅ Good: Each function at its own level
def has_enough_fuel():
    return get_fuel_level() > MINIMUM_FUEL_THRESHOLD

def countdown():
    time.sleep(COUNTDOWN_DURATION)

def launch():
    if has_enough_fuel():
        countdown()
        print("🚀 Launch!")

💡 Practical Tips

Instead of comments:

1. Rename the variable — a → user_age
2. Extract to a function — give it a descriptive name
3. Use constants — if score > 100: → if score > MAXIMUM_SCORE:
4. Break into steps — long code → several short functions

Self-check:

• Read the code out loud — does it sound like an English sentence?
• A friend looks at the code — do they understand what’s happening WITHOUT your explanation?
• Is the comment duplicating the code? — DELETE the comment!

🎯 Summary

Remember: Comments are an admission that your code is unclear. The best comment is no comment at all!