Hacker News Reader

They have value in the code because they save time when someone has to deal with that code a couple of years later. Certainly the explanation could be in the code reviews or the commit message, but it's easiest if it is right there.

View on HN

It's an obvious cliche, but that "someone" is very frequently you. It's really easy to forget why you made some non-obvious decision and waste time poking at the exact same stuff you already did a year or two ago. It's happened to me several times.

When you figure out something tricky, leave a comment.

completely agree every person who leaves detailed “unneccessary” comments like this has been bitten by coming back to a codebase a year+ later and going “who was the idiot that wrote this and why didnt they leave any clue behind” and realizing that yes, you were the idiot. or has had to come behind someone that left zero documentation or readable code and been tasked with cleaning it up. breadcrumbs are useful and comments cost nothing. yes, there are commit messages, but commits often aren’t super clean, explicit, coherent, or even looked at.

Yup. Our operating principle was that if a question was asked in a code review, someone will likely have the same question when reading the code weeks/months/years from now and there should be a comment.

Reply on news.ycombinator.com