I caused a bit of an "incident" at a web dev company I worked at many many years ago by removing commit access from one of the "technical managers", whose hobby was removing every single comment he could find.
"But the code shouldn't need comments," he'd complain, "it should be obvious what it does otherwise it's just bad code!"
Yes, you dobber, it *is* obvious from the code, the *how* is obvious, but the why and the what might not be. The comments explain what it's doing stuff to and why, and in particular why you'd want that and why it's important. Disk space is free, so in a big long comment just write up what that particular bit of business logic is intended to achieve and what it expects as inputs and outputs.
"But the code shouldn't need comments," he'd complain, "it should be obvious what it does otherwise it's just bad code!"
Yes, you dobber, it *is* obvious from the code, the *how* is obvious, but the why and the what might not be. The comments explain what it's doing stuff to and why, and in particular why you'd want that and why it's important. Disk space is free, so in a big long comment just write up what that particular bit of business logic is intended to achieve and what it expects as inputs and outputs.
or, TL;DR "DOCSTRINGS BITCH DO YOU SPEAK IT"