Hacker News Reader

Comment by adamlett | Hacker News Reader

Way to miss the point completely.

But he is actually right: when dealing with obscure implementation details, the best thing to do is to encapsulate it properly, the minimum is to comment it clearly, and ideally detailed explanations should be written in the commit message.

Having a detailed code history isn't in any way an excuse to leave obscure code as is. If you have time to document it, you have time to make the code right.

From what I've seen in the article, the point was to present ways of getting documentation out of commit messages, not implying that they should be used for documenting (which I would disagree with, too).

Of course he is right. But he still completely missed the point of the article, which was not to defend writing or keeping code that is not self explaning. I mean, it's the goddamn premise of the article that you happen to stumple upon a piece of code that's less than perfect! The example in the article describes a situation in which you find a piece of code someone else wrote and you are unsure of what it does or why it's there.To even begin contemplating improving the code, you first have to understand it. The article is about how you can do that with Git logs. So that once you've done that you may proceed to improve it. And yes, extracting it into a well-named method is probably a good way to do that. But that, as I hope we've established, is besides the point.

The premise of the article is that you happen to stumble upon a messy piece of code and that the explanations related to it might be located into the source history. Yet the only reason why these explanations would actually be there is that someone would have enforced doing that as a rule. And the point of the counter-argument is that before enforcing this rule this same person should be enforcing a rule saying that writing messy code like that is prohibited.

In short, maintaining a clean code base has always higher priority than maintaining a clean log.

jesus christ

http://lsolum.typepad.com/legal_theory_lexicon/2003/09/legal...

this article is about recommendations of what to do ex post once a comment-less line of code has been committed in the past that you need to understand. arguments about ex ante things such as how it got there in the first place and how to prevent it from happening is completely orthogonal to the point of the article.

Strong disagree. The article is about recommending and making ex post use of a policy for good commit messages. The point argued is in favor of a future rule for good commit messages. Therefore it is very reasonable to suggest a superior rule for the future.

As rymohr indicated, the author of the code given as example is actually the author of the article himself:

https://github.com/madrobby/zepto/commit/3d92f20966aa02dee82...

Which means the OP genuinely thinks that commits like this one are good practice, and the purpose of the article is to show how to deal with it.

Yet as it was argued above, commits like that should never happen in the first place.

And it didn't. This was the commit that actually happened: https://github.com/madrobby/zepto/commit/2ed0123eaddc023a857...

Notice the code comment. I took it out for the example in the blog post to illustrate how we would deal if there was never a code comment in the first place.

That's like saying that a "counter-argument" to wearing a seatbelt is that drivers shouldn't be getting into accidents in the first place. Yes, it would be nice if all code was well-commented and well-factored with well-named functions, classes and variables, and we should all strive to make code like that. And if that never failed, then perhaps we wouldn't need any other best practices or rules to help us along.[1] But we all know the real world is not like that. We need all the help we can get. Having good practices for writing good code is not, I repeat not an argument against having good practices for commit comments. You make it out to be an either/or proposition. It's not.

I think he got the point. Just that the article is predicated on something incredibly stupid: someone writing a line of code that, to probably most people other than the author, is useless and incomprehensible. I think it's great that the author wrote a detailed explanation in the git commit message, but it's absolutely not enough. That piece of code needs at least a one-line comment there, full stop.

I think the article as a whole is great in that it taught me some things you can do with git that I didn't know before (well, stuff I figured was possible, but didn't know the magical incantations). But it's hard to start reading it and really appreciate all that when the initial premise for explaining all that stuff was... well, someone having a severely bad day when it comes to writing clear code.

> That piece of code needs at least a one-line comment there, full stop.

From my experiences in the real world and from reading comments here, I think there are a lot of people that disagree with that assertion, and it kind of makes me wish I worked in a field where I don't feel like I'm going insane on such a regular basis.

Reply on news.ycombinator.com