Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

I agree that good code self-documents what the code is doing. Good comments document what the code should be doing.

It's important to have both pieces of information in the same place, to minimize the overhead of fixing some subtlety someone might incidentally notice as a side effect of glancing at the code while working on related code.

I can't count the number of times I've run into a complex bit of poorly commented code that looked like it mishandled a subtle corner case, politely emailed the author(s) asking what the intended logic is before claiming I found a bug, gotten the "read the code, dude" response, come back to them with "is the intention really to <insert description of corner case behavior>", and gotten back "my bad, broseph".

There have also been a few times that I've incidentally noticed something looked like it didn't handle a corner case properly in poorly commented code (but not so wrong to obviously be a bug), but failed to follow up with the author due to time pressure on the things I was supposed to be working on, and later had that corner case behavior bite us.



Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: