Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

My favourite Git commit (2019)

dhwthompson.com

Post reply on HN
Print view View original

211–220 of 406 posts

Re: My favourite Git commit (2019)

#211

Post by twosdai »

schacon wrote: post #61

For better or worse, my experience as a GitHub cofounder and author of several Git books (Pro Git, etc) is that the Git commit message is a unique vector for code documentation that is highly sub-optimal. The main issue is that most of the tooling (in Git or GitHub or whatever) generally only shows the first line. So in the case of this commit example would be the very simple message of a generic "US-ASCII error" pro…

Completely agree, the value with the message is really just to link an external ticket Id, the user experience is much better in external ticketing systems for all of the story telling that the article loves.

Don't read "external ticket system" as closed either, plenty systems are open to the public.

Re: My favourite Git commit (2019)

#212

Post by Dylan16807 »

neilkk wrote: post #208
js2 wrote: post #107

Earlier quoted context omitted.

As someone who has contributed to Git since before GitHub existed and who maintains legacy code, I simply cannot disagree more. I use `git blame`, `git log`, and `git show` in the terminal all the time. It's trivial to follow the history of a file. It takes me seconds to use `git log -G` to find when something was added or removed. Nothing pains me more than to track down the commit and then find a commit message tha…

The thing is that writing a good commit message for future people doing `git blame` is only worth it if it's a line of code which someone in the future will look at and need to know why it was changed from its previous form to the current form. If you simply want to comment the current state of the code, you should add a comment in the code. No one will ever need to know in the future why that particular space charac…

> the whole commit message is just a blog entry in the wrong place.

Right. All this wonderful information and detailed error messages need to be findable by someone searching the same error. Someone digging into the code is a very different use case and they need a tiny fraction of that information.

Re: My favourite Git commit (2019)

#213

Post by mixmastamyk »

ChrisMarshallNY wrote: post #181
eschneider wrote: post #117

Earlier quoted context omitted.

When I document, or write commit messages, I don't really _care_ if other folks will ever look at them. Documentation is a gift for future me. If something wasn't obvious to figure out, or a potential source of future problems, I want it written down, so if _I_ go looking for info, it's there. The fact that things are now documented for other folks is just a side benefit.

This. I write documentation for me. Very few folks ever use my published code, which is fine by me. I publish it, because treating my packages as atomic, ship-ready, high-Quality products, forces me to take great care, in each and every one. Which means, when I use them in my other work, I don't have to worry about them. My take on documentation is thus: https://littlegreenviper.com/miscellany/leaving-a-legacy/

Documentation is for everyone. Put it where everyone can read it, not hidden in the most esoteric place possible, via a very unfriendly tool.

I do that often and call it the developer guide. After the user and ops guides.

Not to mention comment and doc strings about why in the current code.

Re: My favourite Git commit (2019)

#214

Post by 6510 »

schacon wrote: post #61

For better or worse, my experience as a GitHub cofounder and author of several Git books (Pro Git, etc) is that the Git commit message is a unique vector for code documentation that is highly sub-optimal. The main issue is that most of the tooling (in Git or GitHub or whatever) generally only shows the first line. So in the case of this commit example would be the very simple message of a generic "US-ASCII error" pro…

Just do a threaded conversation in a comment at the top of each file. Add your name and the date.

Re: My favourite Git commit (2019)

#215

Post by mostlylurks »

Cthulhu_ wrote: post #146
ep103 wrote: post #69

Earlier quoted context omitted.

I know the OP didn't mean it this way, but after reading HackerNews for the last decade or whatnot, it never ceases to surprise me how often developer complaints stem from developers just not doing their damn job. "Almost nobody ever sees it.... nobody reads anything other than the first 50 chars of the headline." On the one hand, I get it. If a tool makes something difficult, people are less likely to do it, and as…

This is the problem with any kind of documentation; while you can write the highest quality, meticulous, most obvious and clearest prose, it's moot if nobody reads it. And nobody reads it because there's so much of it and there's no clear starting point. People just want the summary of what they're looking for. I started to learn Java almost 20 years ago, we had a text book and everything. After the first two chapter…

With commit messages, there is a very clear starting point: the commit message for the commit that last touched the line of code you're looking at with git blame, which is my standard solution for finding out the reasoning behind any piece of code I don't quite understand. Only works for projects that don't destroy their history with squashes or otherwise write uninsightful commit messages (e.g. "fix bug").

Re: My favourite Git commit (2019)

#216

Post by somerandomqaguy »

schacon wrote: post #71
codemac wrote: post #65

Earlier quoted context omitted.

It's great for historical research though. It's one of the few pieces of documentation that will live with the code forever. github and other forms of centralization are not open data formats that folks trivially backup/convert/carry forward. They usually leave the data behind if they move the project somewhere else. So no, I don't think it helps the current community much either. But it helps the debugger years late…

Is it great for historical research? I feel like the format and tooling around it is uniquely _not great_ for historical research. I think it's optimized for discussions before integration, which is largely what PR descriptions and comments are largely used for now. I feel like given great commit messages, determining a story and useful history around any block of code given the Git tooling is incredibly difficult ev…

Tediously commit by commit. But it's often better then the alternative. Design decisions and business logic separately from the code or source control are infinitely harder to reference code against, and realistically that documentation will be lost.

At least if you have the git repo then there's at least some chance to be able to git through the history of some code that's kept with the code. Especially for stuff that code cannot document and you're working with devs that seem to be firmly believe that code is self documenting.

Doesn't mean that every code base needs to have amazing git commits. But code bases expected to live a long time at least give some possibility to string together a history after some work.

Re: My favourite Git commit (2019)

#217

Post by 2devnull »

Big fan of the straussian commit message/commentary style. You read it once and think you understand, but you come back to it much later and understand it in a second, deeper way. There’s an art to this that some people seem to have. Maybe it correlates to taste.

Re: My favourite Git commit (2019)

#218

Post by andrewfromx »

lexicality wrote: post #79
andrewfromx wrote: post #33

I stated using gofakeit's "hackerphrase" for all commit messages. https://github.com/andrewarrow/feedback/commits/main/ hp | git commit -a -F - hp is a golang binary that just spits out a hacker phrase. I have this aliased with the letter q for "quick" so I'm always checking in stuff with q return push done.

that's a great idea but you can make it even more efficient head -c50 That way you'll never accidentally overflow the commit message first line length and no one will even begin to think that the messages might mean something!

this is great. If I do a mix of these + hacker phrase I'll be able to find a commit like, "oh yeah, it's the one right after the urandom bytes.

Re: My favourite Git commit (2019)

#219

Post by daitangio »

A good commit message must explain the reason of the commit (i.e. fix nasty char dncoding issue). This commit is nice but far too long in my humble opinion (and I like to write!) The what is already in the commit diff. Explain the why, trust me.

Re: My favourite Git commit (2019)

#220

Post by ajuc »

kaashif wrote: post #201
ajuc wrote: post #43

Earlier quoted context omitted.

If you change a line of code without doing git-blame on it first you're doing it wrong. I've been bitten by this many times - I change obvious bug, I'm about to commit the changes, I see the previous commit which introduced the "bug" on purpose and the attached JIRA task has perfectly good explanation for why my obvious change would have reintroduced some bug from 2 years ago :)

> If you change a line of code without doing git-blame on it first you're doing it wrong. Working on a project where this is necessary sounds like a hellish experience. The place for comments explaining why the code is needed is right next to the code! On an adjacent line!

> a hellish experience.

It's literally 1 click away. Or even just a hover over the margin.

> The place for comments explaining why the code is needed is right next to the code! On an adjacent line!

And then you refactor the code (from another place) and the function name and parameters change but the comments in adjacent lines remain the same. Ups, the comments lie. After enough time passes it's 50-50 whether a particular comment is still true.

The more high-level the comment - the higher likelihood it lies, because high-level comments are by their nature further away from the code they mention (and they always mention code in many places but you won't copy-paste them everywhere relevant, right? DRY and all). So in reality the comments aren't "on the adjacent line" but "on the adjacent line in one of 10 places this code is related to - go look for all of them".

On the other hand commit message is always on all lines that changed, if you git blame a line - you see when it was changed last and why, and you can be sure nobody messed with it without changing the commit message.

Post reply on HN