Comment on Bill is a pro grammer
potustheplant@feddit.nl 11 months agoThat’s like saying a book’s synopsis shouldn’t exist because you can just read the whole book. Sometimes comments can save you a lot of time and point you in the right direction.
Nah, it’s not, code is modular (IME should be kinda tree-structured), a book is linear.
So the API should be in your analogy the synopsis. And I haven’t said, that there shouldn’t be any comments. E.g. doc-comments above functions, explaining the use-cases and showing examples are good practice.
Books can be modular as well (ever heard of “Rayuela” by Cortazar?) But that’s beside the point. The analogy is fine and it works.
BaardFigur@lemmy.world 11 months ago
Comments also helps explaining why certain non-obvious decisions are made. E.g. a workaround for a bug in a library