Hacker News Reader

Like what? It can’t be the “how” - the code should be able to express that clearly. It can’t be the “what”, again that should be apparent from some combination of code and configuration / metadata.

So that leaves the “why”. To my mind, code comments are the worst place to record why a particular implementation exists. The why often needs collaboration with non-coders.

View on HN

It's definitely the why for any particular unorthodox bits like shims hacks workarounds and the like

The worst is finding some snippet from stack overflow or GitHub without a reference to the issue to back up why this thing is here or perhaps a TODO: with an improvement

I disagree. The code is the best place to comment the why. Regardless of what is documented or what is written up on jira or w/e, the code is what is true.

Commenting the purpose of the code and maybe a link to some documentation allows a future reader to see if the code still fulfills the requirements.

The comments are very often not true, that's why there's so much push back

So they should be updated the same as any other documentation. They're there to help. They don't need to be 100% infallible to be useful.

Reply on news.ycombinator.com