Rant: A senior dev told me my comments were too detailed

Was working on a Python project at a meetup in Austin. This guy with 15 years experience looks at my code and says "you're writing a novel in there." He showed me how to use self-documenting functions instead. Cut my comment count by 80% and code got cleaner. Anyone else get told their code needs less explaining?

2 comments

2 Comments

the_simon1mo ago

cut my comment count by 80%" - that's wild, I had the exact opposite wake up call like 6 months ago. I was the guy who thought every line needed a play by play, felt proud of my "thorough documentation". Then a senior dev just deleted half my comments in a PR and said "if this needs a comment, the code is wrong". It stung at first but honestly they were right. Now I only comment on the weird edge cases or business logic that isn't obvious from the function name. Your mileage may vary, but self-documenting code really does make everything easier to read.

ninasanchez1mo ago

Feels like this whole "self-documenting code" thing gets treated like some kind of universal law but I've seen plenty of messy codebases where even the most obvious functions turn into spaghetti after a few months. Like yeah, clean code is great and all, but sometimes a comment explaining WHY you chose a weird XOR operator over a simple if statement saves everyone an hour of staring at git blame. Maybe your senior dev just had a bad day and took it out on your comments.