Every line of code is always documented • Hacker News Board

Re: Every line of code is always documented

#21

Post by jpatte » Sat, Feb 08, 2014, 9:11 PM UTC

adamlett wrote: post #19

RyanZAG wrote: post #9

You really shouldn't have to be relying on history for all of that context. It should definitely have been a function simply called 'triggerLayout()'. Then the exact and best method for triggering layout could be put in that function and used throughout the project where necessary, and easily updated if a better method of triggering layout comes along. Code like this is extremely brittle with or without that git hist…

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.

Re: Every line of code is always documented

#22

Post by dasil003 » Sat, Feb 08, 2014, 9:19 PM UTC

RyanZAG wrote: post #9

You really shouldn't have to be relying on history for all of that context. It should definitely have been a function simply called 'triggerLayout()'. Then the exact and best method for triggering layout could be put in that function and used throughout the project where necessary, and easily updated if a better method of triggering layout comes along. Code like this is extremely brittle with or without that git hist…

That may be true for the given example, but it doesn't work that way for all the nuances of code that come up. For one thing because English wording has ambiguities, and for another because there are so many concerns with some cross-cutting each other that you can only break things down into atomic functions to a certain degree.

I think the overall point of the article rings very true: great VCS habits pay dividends over time regardless of how well-crafted the code itself is.

Re: Every line of code is always documented

#23

Post by userpasswd » Sat, Feb 08, 2014, 9:25 PM UTC

jpatte wrote: post #21

adamlett wrote: post #19

Earlier quoted context omitted.

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

Re: Every line of code is always documented

#24

Post by jkrems » Sat, Feb 08, 2014, 9:25 PM UTC

etler wrote: post #8

shaggyfrog wrote: post #3

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.

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…

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.

Re: Every line of code is always documented

#25

Post by gtirloni » Sat, Feb 08, 2014, 9:31 PM UTC

Checking the history is much slower than a comment right there in the code. Repeat this a thousand times and you've lost precious time hunting for information.

Re: Every line of code is always documented

#26

Post by rymohr » Sat, Feb 08, 2014, 9:39 PM UTC

Great article! Mislav definitely knows his git.

What he didn't point out though is that he was actually the one that contributed that code in the first place.

https://github.com/madrobby/zepto/pull/586

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

As others have commented, long explanations like this have no place in commit messages. Comments should always be used to explain what you're doing and why you're doing it. Commit messages should simply summarize what you did.

A better commit message would have simply been:

fix animate() for elements just added to DOM

See included comments for explanation.

Re: Every line of code is always documented

#27

Post by darryl42 » Sat, Feb 08, 2014, 9:40 PM UTC

gizmogwai wrote: post #4

I wish my current coworkers wrote any comment in there commit message...

I wish management allowed comments. Commits are work item number and title or work item only. Comments in code are actively removed.

Re: Every line of code is always documented

#28

Post by adamlett » Sat, Feb 08, 2014, 9:59 PM UTC

jpatte wrote: post #21

adamlett wrote: post #19

Earlier quoted context omitted.

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.

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.

Re: Every line of code is always documented

#29

Post by Zitrax » Sat, Feb 08, 2014, 10:02 PM UTC

etler wrote: post #6

This is exactly why I'm such a bastard when it comes to git history. A clean history isn't something that just gets filed and disappears forever. Unfortunately, lots of people think it's ok to use a message like "fixed stuff". Don't even try that in my codebase though.

Or totally empty commit messages.

Re: Every line of code is always documented

#30

Post by etler » Sat, Feb 08, 2014, 10:14 PM UTC

RyanZAG wrote: post #15

etler wrote: post #13

Earlier quoted context omitted.

"Code happens". In reality, there's code that should have been commented all the time and even in the best codebases. I don't think there's a coder in the world who hasn't had a time when he's looked back on a piece of code and just thought "what?". If you get in the habit of keeping a well documented git history, it's an invaluable resource. I find on top of these benefits, having to explain what changes I made also…

What? No, it's got nothing to do with commenting. It's to do with basic code design: put your stuff in functions. A line like that should have been in a function to start with, and it should have been caught during a code review or as common sense by the committer before he even committed.

The point of the article has nothing to do with the code snippet. My point has nothing to do with the code snippet. It's just about code in general, and it's never as easy to understand as you want it to be.