4 ms·

I think sometimes you want to put why in a comment. Just today I wrote a two paragraph comment (usually I don't write many comments at all) that describe the b

I think sometimes you want to put why in a comment. Just today I wrote a two paragraph comment (usually I don't write many comments at all) that describe the business need for why this the code is necessary (in my case, connecting to a 3rd party data source that overshares, describing the nature of the oversharing, outlining the -- very complex -- steps in the pruning algorithm, and noting that there are corner cases we might miss and also noting that we shouldn't care -- a handful of bad apples in a machine learning algo will probably disappear in the wash).

lugged 5y ago
Yup, I rarely ask "what's this code do" or "how does this code do that". But "why the fuck" is a daily occurrence. Self documenting code explains how and what. If you need a comment to explain how and what its a code smell. Sometimes it's ok but ideally it should be rare. I try not to overcomment but when I write code that looks confusing or clever I try to explain why I've done it that way. If I'm optimising, I'll explain why. If I'm making an assumption about something related but elsehwere I'll explain that. If I'm leveraging some context that isn't explicit, I'll explain that. ... Also, type of code matters, glue code rarely needs exhaustive comments. Library code often gets line by line commentary so when someone comes in to change something for their use case they have a clear understanding of what they're really changing, and who and what might break because of their change. I notice library code tests often get more comments explaining what and why I'm adding an assertion. Glue code test rarely needs comments in tests.