Hacker News Reader

Comment by shaggyfrog | Hacker News Reader

It sounds like "this.get(0).clientLeft" should have been a single-line function named something like triggerLayoutInMozillaAndFirefoxToFixAnimateForNewDomElement, or if you don't like massive function names, a comment that says that.

Spelunking through commit history shouldn't be necessary learn the intentions behind those kinds of actions.

View on HN

It doesn't matter if it should have been commented or not. The reality is it wasn't. If you get in the habit of explaining your changes in git messages, every line change will have documentation, or at least an owner so you can ask them about it.

If you do need to go git spelunking to figure out what's going on, you'd have to be insane to not add a comment afterwards.

Either way, "shoulda coulda woulda". If the code doesn't have a comment, it doesn't have a comment. These things happen, and you can't change the past. But with git, you can relive it.

According to your logic, the author of this code should write a detailed explanation in the commit message, except he probably won't. Shame isn't it?

Reality could also have been: the commit message wasn't as helpful. Or the message would have been but the file was moved, copied, the indentation level changed, or any number of things that destroys the connection to the original comment. The article sounds like it advocated treating the commit message as the primary means of documentation - which is hardly a good practice. Meaningful identifiers/function names, and comments for non-obvious code should come first. If someone prioritizes elaborate commit messages and a clean history before good code, the techniques outlined in the article might be useful, for sure. But it says: "A project’s history is its most valuable documentation." - which is, frankly, not true for most projects. And if it is true, it's a bug, not a feature.

I did not interpret the article as being git should be a primary source of documentation at all. I have a hard time seeing which part of the article implies that. I think he's just pointing out how it's another tool you can use.

From the article:

A project’s history is its most valuable documentation. (...) The quality of this documentation, however, relies heavily on the diligence of the people involved while writing commit messages.

Requiring such diligence when writing commit messages, while at the same time allowing the same people to write opaque code as shown in the example, would be absurd.

Reply on news.ycombinator.com