I'm currently building a simple card game in Python to improve my programming skills. As my codebase grows, I'm feeling the urge to add more comments for clarity. However, I'm worried that too many comments might clutter my code, making it hard for others (or even myself later) to read. I've seen conflicting advice online, so I thought I'd ask specifically about my code and how to find a good balance. Here's a snippet of my code for context.
```python
def hit():
card = drawCard() #draws a card, "1H", "KS", "4D" etc
cardValue = card[0] #first character refers to the value, "one", "king", "four",
cardWorth = 0 #cardWorth being the value of the card that we're going to return
if cardValue in v.faceCards: #if we draw a card where the first character, cardValue is a j, q, k, a,
cardName = v.faceCards[cardValue] #we assign the cardName that we'll return using our list of facecards
cardWorth = 10 #assigns a universal face card worth
elif cardValue == "a": #since aces don't follow our universal value, we assign it a default value of 11
cardName = "ace"
cardWorth = 11
else: #if we dont draw a facecard
cardName = cardValue #we assign the name to the number, "1 for 1", "4 for 4" etc
cardWorth = int(cardValue) #since we know our cardValue is an int and not a str, we can add it to our cardWorth using int()
v.cardIdens.append(card) #appending the full card identification we drew earlier to a list, for other purposes.
return cardName, cardWorth
```
5 Answers
Hey, it's great that you're learning! Generally, if a comment explains 'why' something is done rather than just describing 'what' the code is doing, it’s useful. For example, your comment like `# since aces don't follow our universal value...` is solid because it gives context. However, comments like `# draws a card` aren’t really needed since the function name `drawCard()` already makes it pretty clear.
I'm a big fan of self-documenting code too! Using meaningful variable names and type hints really helps. For more complex functions, a docstring is a good idea. Keep your comments for parts that truly need extra explanation because of complex logic — otherwise, it can just become noise.
Remember that in professional settings, clear variable and function names can reduce the need for comments. Comments that simply restate what the code does (like `x != y # checks if x != y`) don’t add value. If you stick to explaining why certain decisions were made, you’ll create cleaner, more maintainable code.
I’d suggest looking to reduce those comments where you can. For example, after `os.path.exists(PATH)`, you shouldn't need `# check if path exists`. It's already clear! Good naming can often negate the need for comments. Use descriptive names for your functions and variables to help others understand your logic without too much explanation.
When you're just starting out, it’s okay to have comments to help guide you through understanding your code. But the goal is to get to a point where your code tells its own story through good structure and naming. For instance, creating a `Card` class could help encapsulate the card logic and avoid needing as many comments in the `hit()` function.
Yeah, I think explaining 'why' is key too! If a comment helps you grasp the code better as you're learning, it's fine to have some extra notes. But as you advance, aim to write self-explanatory code to reduce clutter.