Hacker News Reader

Comment by biofox | Hacker News Reader

Development is like a one-way hash function: a line of code may have been added and structured a particular way for any one of an infinite number of reasons.

Without the documentation (the forward mapping) there's no way to exactly predict its intended function, leading to all sorts of misunderstandings further down the line when someone tries to reverse it.

View on HN

Doesn't need re-explaining but makes me realise we often talk about comments explaining what code does, which leads to "your code should be well-written so it's easy to understand what it does" or "I'm a good developer, I can understand that easily by reading it".

But as you say the question is why - people will often be reading existing code because of a bug, so clearly the thought process that created it had a faulty step somewhere.

Really, what people think should go in comments should instead go to commits, which is actually a snapshot of what the author was trying to achieve during a point in time.

Inline comments just become out of date or mangled. Commit revisions are the source of truth.

The problem with commit messages is that they quickly get buried in the log, and are difficult to dig up. It's not perfect, but comments stay with the code throughout the versions.

git blame will usually give you the last edit of a line, which I find is fairly easy to see the last time it was changed (and then if you want to know how things were done earlier, do the same on its parent commit)

Reply on news.ycombinator.com