I was convinced my code needed more comments, then a friend showed me his screen

For months, I wrote a comment for almost every line in my Python scripts. I thought it made my work clear. Then a buddy, who's been coding for a few years, looked at a script I made for a budget tracker. He said, 'This is like reading the same thing twice.' He opened one of his own files. The code was clean, with clear variable names like 'monthly_total' instead of 'x', and only a few comments explaining why a tricky bit worked, not what each line did. He pointed out my line '# add tax to total' right above 'total = total * 1.07'. The code already said what it did. That one look changed my whole approach. Now I focus on writing code that explains itself first. Has anyone else had a moment where they realized they were commenting too much instead of writing clearer code?

2 comments

2 Comments

cameroncarr4d ago

Ever think about how too many comments can actually make a script harder to update? If you change the logic, you have to remember to change the comment too, or they get out of sync. I agree with @paulw63 about explaining the "why", but I'd add that a good test name can sometimes replace a comment entirely, like test_calculates_tax_for_edge_case().

paulw634d ago

Yeah, that's a classic new coder move. I probably wrote a thousand useless comments on my first big project. The rule I go by now is, comment the "why" if it's not obvious, never the "what". If you find yourself describing the action, you need a better variable or function name. Like, calculate_tax(total) is way clearer than a comment.