KISS: Write Simply, Write Clearly 🎯

Does your code work? Great! But there’s one more important criterion — readability. Code is written once and read hundreds of times. Your teammates (and future-you a month from now) should be able to understand it at a glance.

🎯 The KISS Principle

KISS = Keep It Simple, Stupid

It sounds blunt, but the intention is noble: don’t overcomplicate things unnecessarily.

What Does It Mean?

❌ Bad:

# Check if a number is divisible by 2
def is_even(n):
    # Get the remainder when dividing by 2
    remainder = n % 2
    # If the remainder is 0, the number is even
    if remainder == 0:
        return True  # Yes, it's even
    else:
        return False  # No, it's odd

✅ Good:

def is_even(n):
    return n % 2 == 0

The second version is 10 times shorter and does exactly the same thing. It’s easier to understand, easier to change, and harder to break.

💬 The Problem with Comments

When Are Comments Harmful?

Many people think: “More comments = better code.” That’s a myth!

Bad comments:

❌ They duplicate the code:

# Create a list of creatures
creatures = []

# Append dragon to the list
creatures.append(dragon)

# Print the length of the list
print(len(creatures))

These comments add nothing. The code is already self-explanatory.

❌ They explain bad code instead of fixing it:

# This variable holds a flag to check that the game is not over
# and that the player still has cards and that the enemy is also alive
flag = True

Better to just name the variable properly:

game_active = True

❌ They go stale:

# Check that health is greater than 10
if health > 0:  # Changed the logic, forgot to update the comment!
    print("Alive")

The code changed, the comment didn’t. Now it lies!

When Are Comments Useful?

✅ Explaining “WHY”, not “WHAT”:

# Use a copy of the list so we can remove items during iteration
for creature in creatures[:]:
    if creature["health"] <= 0:
        creatures.remove(creature)

✅ Documenting complex logic:

# Damage formula: base_attack * (1 + crit_chance * crit_multiplier)
damage = attack * (1 + crit_chance * crit_multiplier)

✅ Warning about gotchas:

# WARNING: don't call this in a loop — it's a slow function!
result = calculate_complex_physics()

🧹 Clean Code Instead of Comments

Instead of commenting what the code does, make the code self-documenting:

1. Good Variable Names

❌ Bad:

# Player damage
d = 15

✅ Good:

player_damage = 15

2. Short Functions

❌ Bad:

# Complex battle logic spanning 100 lines
def battle():
    # ... massive function ...

✅ Good:

def battle():
    choose_attacker()
    apply_damage()
    check_death()
    check_victory()

Each function does one thing and has a descriptive name.

3. Separate with Blank Lines

Instead of a comment like # Start of battle — just add a blank line:

player_hand = deal_cards(creatures_library, 3)
enemy_hand = deal_cards(creatures_library, 3)

while len(player_hand) > 0 and len(enemy_hand) > 0:
    player_attack(player_hand, enemy_hand)
    enemy_attack(enemy_hand, player_hand)

A blank line visually separates the logic. Easier to read than with a comment.

📋 Clean Code Checklist

Before submitting for review, check:

✅ Code works (all functions are tested)
✅ No commented-out lines (delete old code)
✅ No leftover debug print()s (if you used them — remove them)
✅ No duplicate comments (like # create a list above list = [])
✅ Variables are named clearly (player_health instead of ph)
✅ Functions are short (under 20 lines is ideal)

🎮 Game Example

❌ Before KISS:

# Function to check if a card is dead
def check_dead(card):
    # Get the card's health
    hp = card["health"]
    # Check if it's less than or equal to zero
    if hp <= 0:
        # If yes, return True
        return True
    else:
        # Otherwise False
        return False

# Check the player's card
if check_dead(player_card) == True:
    # Remove the card
    player_hand.remove(player_card)

✅ After KISS:

def is_dead(card):
    return card["health"] <= 0

if is_dead(player_card):
    player_hand.remove(player_card)

Result:
- 13 lines → 5 lines
- Removed all unnecessary comments
- Renamed the function (is_dead is better than check_dead)
- Removed the redundant == True comparison

💡 The Golden Rule

The best comment is not needing one.

If code needs an explanation — rewrite the code, don’t add a comment.

🚀 What’s Next?

• ✅ Review your code: are there unnecessary comments?
• ✅ Rename unclear variables
• ✅ Break long functions into shorter ones
• ✅ Delete commented-out code

Simple code = reliable code! 🎯