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 ...
pass
โ 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! ๐ฏ
๐ฌ Comments (0)
No comments yet
Be the first to share your opinion about this article!