4 ms·

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 cle

by jpatte 13y ago

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.

userpasswd 13y ago
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).
adamlett 13y ago
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.
- jpatte 13y ago
  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.
  - gfodor 13y ago
    jesus christ http://lsolum.typepad.com/legal_theory_lexicon/2003/09/legal_theory_le_2.html 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.
    - Dylan16807 13y ago
      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.
    - jpatte 13y ago
      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/3d92f20966aa02dee8249daaefc5f8b6623e00de 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.
      - mislav 13y ago
        And it didn't. This was the commit that actually happened: https://github.com/madrobby/zepto/commit/2ed0123eaddc023a8579df0a3a084a70a392d792#diff-700e1d5a001554f97044d4364a5b357eR89 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.
  - adamlett 13y ago
    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.

by jpatte 13y ago

userpasswd 13y ago

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).

adamlett 13y ago

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.

jpatte 13y ago
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.
- gfodor 13y ago
  jesus christ http://lsolum.typepad.com/legal_theory_lexicon/2003/09/legal_theory_le_2.html 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.
  - Dylan16807 13y ago
    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.
  - jpatte 13y ago
    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/3d92f20966aa02dee8249daaefc5f8b6623e00de 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.
    - mislav 13y ago
      And it didn't. This was the commit that actually happened: https://github.com/madrobby/zepto/commit/2ed0123eaddc023a8579df0a3a084a70a392d792#diff-700e1d5a001554f97044d4364a5b357eR89 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.
- adamlett 13y ago
  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.