[HN Gopher] My favourite Git commit (2019)
___________________________________________________________________
My favourite Git commit (2019)
Author : karagenit
Score : 443 points
Date : 2024-02-01 15:46 UTC (7 hours ago)
(HTM) web link (dhwthompson.com)
(TXT) w3m dump (dhwthompson.com)
| aeurielesn wrote:
| I had a terrible time when someone used "smart quotes"
| (beautified Office quotation marks) in a configuration file. I
| believe this was only possible because they copied it from
| Outlook.
| karagenit wrote:
| Yeah, I've been bitten by those quotes in the past too. I
| noticed recently that VSCode (probably other IDEs too)
| highlight these characters pretty clearly to help avoid these
| issues.
| jboy55 wrote:
| I wonder how much infighting there was between orgs at
| Microsoft over this. with an Outlook/Word PM escalating...
| "Make the languages understand smart quotes!"
| atahanacar wrote:
| >smart quotes
|
| I never understood why a "stylistic" choice requires separate
| characters. If we don't need a serif and non-serif version of
| every character and instead leave it to the software, why can't
| we do the same with the "smart" quotes?
| kristjansson wrote:
| Typographic quotes are left- and right-handed, vs. the ASCII
| double quote which is just a single character:
| "quoted" "quoted"
|
| Who in the blazing highs of techno-utopianism fervor thought
| it was a good idea to automatically translate the latter to
| the former we'll never know.
| atahanacar wrote:
| Why not stylize it as typographic but store it as a
| "regular" double quote though?
| mbork_pl wrote:
| How do you handle non-paired ones then?
| maleldil wrote:
| Render them as standard double quotes? The same way
| Markdown renders a single backtick as just a backtick,
| but text surrounded by backticks becomes code.
| mbork_pl wrote:
| Nice try, but the problem with this is that typography is
| _really_ complex. For example, there is a rule in English
| typography (I'm not sure if it's often used today though)
| that when you have a quotation spanning several
| paragraphs, you should put an _opening_ quote at the
| beginning of each paragraph - but only one _closing_ one
| at the end of the quote.
| tuetuopay wrote:
| I'm french and I actually really like the auto-translation.
| This way software that does not care about which quote
| those are (mail, web, etc) can swap them, and where it
| matters then it does not translates it (vim, etc).
|
| Sadly the new official french azerty keyboard has
| _dedicated_ keys for both opening and closing quotes, and
| the good ol ' simple quote tucked away behind modifier
| keys. As a dev I hate it. (arguably I should not even use
| azerty for development but that's another issue)
| jotaen wrote:
| > I never understood why a "stylistic" choice requires
| separate characters.
|
| I don't think it's a purely stylistic choice, there is
| actually semantics to it: " opening
| quotation mark, i.e.: starts the quote " closing
| quotation mark, i.e.: ends the quote
|
| You could otherwise make the same point about parenthesis:
| why not just |do this| instead (of this)?
| thaumasiotes wrote:
| It's not a stylistic choice. Opening quotes and closing
| quotes are different things, and it isn't possible to tell
| the difference (when not already provided) without parsing
| the language in which they're used. That's why in TeX you
| have to manually specify which kind you want, and in software
| like Wordpress that just guesses, the guess is usually wrong
| and your published text looks ridiculous.
| mgdlbp wrote:
| "quote unification'': most typefaces: "Hello"
| ,,Hallo"
|
| Verdana: "Hello" ,,Hallo"
| euroderf wrote:
| For a long time there was a Perl script called the Demoronizer
| that fixed this kind of nonsense.
| selimthegrim wrote:
| I think this pops up in MacOS shells too
| dblitt wrote:
| IIRC TextEdit.app has options like smart quotes, auto
| capitalize, and spell check turned on (in addition to being
| rich text by default), so you have to change all those to be
| a dumb plain text editor.
| fishyjoe wrote:
| TextEdit and the Notes app have both caused me to
| copy/paste the specialized quotation marks.
|
| Now I only use vim as a scratchpad because I've been bitten
| too much by GUI apps
| keybored wrote:
| In other words real quotes that people use in published
| writing.
| OJFord wrote:
| One thing I disagree with is:
|
| > I wouldn't expect all commits ( _especially ones of this size_
| ) to have this level of detail.
|
| (emphasis added) - actually in my experience it's often the
| little ones, innocuous looking things that might really need a
| relatively longer explanation.
|
| Yesterday I wrote three paragraphs on why I added `--limit=999`
| to a `gh pr list` because it's confusing: there's already a
| `limit(` in the `--jq` argument, and the higher it is (given say
| infinite PRs in total) the lower the end result will actually be.
| (Yes I wrote a comment too. And probably spent even longer
| thinking about and working it up than writing about it; hopefully
| I'll recall it as an example the next time someone implies the
| job is about churning out code!)
| pdpi wrote:
| I find myself commenting code in a similar pattern: A small
| kernel of "interesting" code that has a 1:1 ratio (or higher)
| of comments to code, which enables the rest of the codebase to
| be "boring" self-documenting boilerplate-y code that doesn't
| really warrant much in the way of commenting.
| keybored wrote:
| For a commit that adds a language binding (and might be 100+
| additions/deletions) I might just say "Add X function". Because
| I'm just following established patterns. But for the linked
| kind of change? Yeah, several paragraphs of explanation is
| definitely useful.
| unregistereddev wrote:
| I agree with you that the little innocuous things often need a
| longer explanation, but the linked commit message is way too
| long IMO. It either wastes the readers' time, or it causes the
| readers' eyes to gloss over at the wall of text. You don't need
| to document your entire journey in order to document your
| findings and explain why.
|
| > This was a non-ascii whitespace character that caused
| `ArgumentError: invalid byte sequence in US-ASCII` when running
| `bundle exec rake`
|
| ^ should be sufficient. It includes enough keywords to come up
| in a search if someone has a similar problem in the future, it
| contains the root cause of the problem, and it is short enough
| that people are unlikely to gloss over it.
| mbork_pl wrote:
| The article explains why all the rest is, maybe not needed,
| but good to have.
| OJFord wrote:
| Yes, it's not my preferred style either, but it's much better
| than 'fixes error' type thing, subject line only, that's so
| common.
|
| I like the form: Fix ArgumentError 'invalid
| byte sequence' Non-ASCII whitespace characters
| cause [...]. This was apparent in [...] because [...].
| This commit fixes the issue by removing the offending
| character; so the file is now solely ASCII characters.
|
| Or that sort of thing. Subject tells me why, body tells me
| what the problem was and how it was fixed. (Who, when, where
| are already in the commit metadata! The diff shows a very
| literal 'what' too, the what/how in the body should offer
| context and explanation as required.)
| dlvhdr wrote:
| I do appreciate them but they're just a pain to write sometimes
| spenczar5 wrote:
| I have felt that pride in writing a great commit message, but I
| am less sure of the value to others. I don't think most people
| search commit messages when they encounter an unusual error
| message, or when adding a new feature, or really almost ever.
|
| It's a bit sad, but I have a growing suspicion that beautiful
| commit messages are a bit of vanity by the programmer. The person
| primarily impressed is often the author; others will walk on by
| without noticing.
|
| There is room sometimes for those aesthetic flourishes but I am
| not convinced they have much practical value, and I have stopped
| really being bothered by commit messages of "fix whitespace
| issue" from others. I think I am a better colleague for that.
|
| Things might be different on a project like Git or Linux with
| huge distributed teams and tons of commits, versus the projects I
| am used to which have between 1 and 100 contributors, mostly from
| the same organization.
| j2kun wrote:
| I find them valuable, especially when trying to study a new
| codebase. In the current era where we get immediate feedback on
| everything we post online, it's harder to see the value that
| comes from writing good commits, and the value can be delayed
| by weeks, months, or even years.
| cybrox wrote:
| If anything, this just tells us that tooling should incorporate
| commit messages a lot more. While these kind of messages are
| most valuable in large projects, there are some of them in a
| lot of projects and they could have saved a lot of time.
|
| Especially now with AI IDE integrations, incorporating a
| software's whole history into supplemental tools would be more
| useful than ever before.
| bombcar wrote:
| > I have felt that pride in writing a great commit message, but
| I am less sure of the value to others. I don't think most
| people search commit messages when they encounter an unusual
| error message, or when adding a new feature, or really almost
| ever.
|
| They have value even if the only person who will ever look at
| them is you - and I will say that when bisecting an issue, the
| commit message of the commit I finally find is really useful
| (or it could be if it wasn't _fixed thing_ ). It also means
| that if you encounter a similar issue again, you know that
| there's a note on a commit you can find.
| tux3 wrote:
| In some orgs, people never run a bisect. Not once a year.
|
| They go as far as squashing out swaths of history into big
| un-reviewable blobs. Once code has been merged, they never
| look inside a past commit again.
|
| In spite of isolated (desperate) demands for rigor, it works
| fine.
| tuetuopay wrote:
| I despise squashs. It encourages people to tread git commit
| as a glorified ^S of their work.
|
| You want to know why a change was made, or who so that they
| can explain it. You land on a blob of a diff, with no
| meaningful commit message (any commit message was squashed
| to /dev/null to be replaced with the MR title and
| description). And then off you go to the corresponding
| github/gitlab/whatever MR only to find a wall of "hmmmm"
| "why no work?" "try something" etc commits.
| bspammer wrote:
| This is a false dichotomy. Someone creating the "fix
| problem" commits is not going to suddenly write great
| commit messages because the merge strategy changed.
|
| The root evil is actually MRs that live longer than a day
| or two, and change too much code at once.
| mrinterweb wrote:
| Sometimes units of work that a branch would reflect are
| larger. I agree there are some branches that grow larger
| than they should, but often there are branches that
| involve a good number of changes, and breaking it into
| smaller branches doesn't really make sense either. There
| will always be branches where there should be multiple
| meaningful commits, and automatically squashing them all
| together just defeats the purpose of good commit
| messages. I don't buy into the idea that branches should
| always have just one commit or be reflected as a single
| commit on merge.
| adamsilkey wrote:
| Squashes and rebaseses, used properly, are done prior to
| committing work into a shared major branch (like trunk or
| develop or whatever). The goal of the squash is to make
| the resulting commit atomic.
| bandyaboot wrote:
| Most of my commits are indeed a glorified ^s. Doing this
| does require some discipline though. You've got to pay
| attention to when you've reached a point that the
| accumulated changes represent a reasonably small, but
| complete unit of work that should be squashed and
| documented with a good commit message.
| anthomtb wrote:
| I agree with this wholeheartedly. If writing a detailed,
| multiparagraph commit message, assume the target audience is
| future you.
|
| Most likely, a time-pressed dev on the far side of the world
| will think your commit broke something and send a 2:00 AM
| message of "URGENT: code broke CRITICAL customer request"
| with a link to the commit, whatever JIRA issue they are
| working on, and zero additional context. They will NOT bother
| to read the message (likely explaining how they got into
| their pickle in the first place) but will see your email,
| send a message, and do whatever it is they do while waiting
| for someone else to figure out the problem. You, being that
| someone else, will now have an excellent starting point on
| the top priority for the day. Much better than if your
| message had just been "fixed it".
| pletnes wrote:
| I often use the git blame feature in the IDE to understand
| what's been going on. A good commit message will be
| appreciated, should I happen to find one.
| Lex-2008 wrote:
| I was bitten by too-short commit messages few times already,
| when someone asks me "why is it done this way?" - I check git
| history to find my own 3-year-old commit with message "it
| should be done this way"... Since then I try to write my commit
| messages so at least future me would get a hint why a change
| was necessary.
| ajuc wrote:
| 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 :)
| boolemancer wrote:
| Seems to me that if you're introducing something that seems
| like a bug on purpose, you should probably have the comment
| in the code explaining why it's there.
| kaashif wrote:
| > 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!
| ajuc wrote:
| > 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.
| wnoise wrote:
| Why code is needed is different than why change is needed.
| gotts wrote:
| I agree with you that searching across commit messages happens
| rather rarely so return on great commit messages might be
| questionable
|
| where great commit messages like the one in the blog post make
| perfect sense are pull requests. If the commit message explains
| the whole thought process that the author had while working on
| it, it saves so much time on pull request review.
| 20after4 wrote:
| I might be weird but I try to at least skim all of the commits
| on any project I am actively involved with. If it's an open
| source project then those commit messages will live on forever.
| They will even be indexed in regular search engines, not just
| code search (this maybe not so much now that GitHub is locking
| out bots more and more)
|
| When I'm trying to solve a problem and not finding results on
| google or stack overflow, sometimes I search GitHub just to see
| if a similar thing shows up in PRs or commit messages anywhere
| (including private repos I have access to search). It's helped
| me out on countless occasions. Good commit messages do have
| value beyond vanity, absolutely without a doubt. The fact that
| many developers aren't looking, that's their loss and hopefully
| they will see the light once they have enough experience. Maybe
| teach a junior dev how to search them! Maybe link them to TFA.
| slily wrote:
| I agree this one goes into more detail than is useful for
| future reference, most of the explanation would be better off
| in a PR description. But in general I would rather people go
| into too much detail than the more common variant of not
| providing any contextual information anywhere (or only in a
| chatroom at best) and sticking to one-line commits. As long as
| the important information is near the top so I don't have to
| wade through the verbose "this is how I discovered this issue"
| thing, go crazy.
| cheald wrote:
| IMO, the primary target audience for good commit messages is
| the same target audience as good code comments: me six months
| from now. Being able to read why and how a particular thing was
| done has helped me in debugging and troubleshooting an issue on
| more than one occasion.
| kelnos wrote:
| I both agree and disagree. I think you're right that most
| commit messages won't end up being seen. But when you do need
| to see one, having a good commit message can be critical to
| understanding a change, especially if the person who made the
| change is long gone by the time you need to look at it. Or,
| hell, if that person was you, but it was far enough in the past
| that you don't recall the details.
| thefourthchime wrote:
| I agree. My view is that you shouldn't write comments because
| if you have to, then your code isn't clear or organized well
| enough. If you do need a comment, perhaps to document a
| "Chesterton's Fence", you should put a big nice comment block
| to explain why and what's going on.
|
| The reality is people don't like to read, if they do it'll be
| an overview of how the code is organized, they don't want to
| read git commits or even comments. The code is the only truth.
| GPT can already explain in English what the code is doing
| pretty well already, imagine in 2-3 years.
| keybored wrote:
| Here is a context-full commit message.[1]
|
| This is so common that the maintainer wrote this[2]
|
| [1]
| https://github.com/git/git/commit/d70f554cdf38b0b05cfaa8e8eb...
|
| [2] https://lore.kernel.org/git/xmqqedevo8ps.fsf@gitster.g/
| Zambyte wrote:
| I guess it makes sense that it's a common name, but I was
| expecting this David Thomson[0] instead :-)
|
| [0] https://dthompson.us/
| excitom wrote:
| It's a great commit message, but could be even better with "TL;DR
| non-breaking space in a comment can cause parser problems".
| adrianmsmith wrote:
| I think the disadvantage with this style of documentation is you
| can't really alter the commit message after it's written.
|
| (I mean you could obviously with "rebase" but are you really
| going to alter something written one year ago, already merged to
| "main", and cause a bunch of pain with everyone's feature branch
| etc.?)
|
| Compare that with documentation stored in a .md file, or even a
| Wiki or even Confluence. My colleague can write something and if
| I see a way to improve it I can go ahead and do that, and other
| colleagues can improve on what I've written.
|
| In this particular case I suppose the bug is fixed and won't come
| up again. But I also myself find it tempting to describing the
| design of a particular component when I commit that component,
| and that's something I now avoid. What about when that component
| needs to be changed by a future commit e.g. due to the business
| requirements changing? Will the commit documentation just
| describe the differences? Then in order for a new team member to
| find out how the system works by reading the documentation
| they've got to read multiple commit messages and "merge" them in
| their head.
| macintux wrote:
| There's no reason this documentation can't be replicated in
| another context, and for all we know it was.
| tyrust wrote:
| I think commit messages are mostly valuable for a future code
| reader asking "why is this bit like this?" and then looking at
| blame logs for the answer. As you point out, bigger picture
| stuff ought to be elsewhere (documentation, tracking bug).
|
| Keeping docs in version control and including doc changes with
| the code changes is a nice way to address your concern.
| josephg wrote:
| I really think git made a mistake in conflating the immutable
| log of _what_ was changed with the (ideally mutable) story of
| what got merged in. So you see people arguing over squashing
| commits vs rebasing vs merging. Squashing commits makes the
| history of commits a better story of features being added.
| Merging preserves the immutable log of the actual changes made
| to the code, and rebasing sort of does a bit of both.
|
| But, I don't see any reason we can't have our cake and eat it
| too. We're programming computers after all and we can make them
| do whatever we like.
|
| If I wrote my own git, I think I'd split commits into those two
| parts. I'd leave the history of changes immutable - probably
| with some sort of Merkle DAG like Git does. And then have a
| separate associated data store which stores the commit
| messages, in a nice sensible, editable log describing the work
| that actually happened. Let people arrange and rearrange the
| commit descriptors however they like. If you want, group
| commits around feature tags, fix typos and make any changes to
| the messages that you want. But, the whole while the underlying
| log of diffs ("what actually changed in the code") can remain
| (gloriously) unaffected.
| zilti wrote:
| Fossil has something a bit like that.
| wnoise wrote:
| Can you elaborate how?
| passivegains wrote:
| > I really think git made a mistake in conflating the
| immutable log of what was changed with the (ideally mutable)
| story of what got merged in. So you see people arguing over
| squashing commits vs rebasing vs merging.
|
| Every team I've been on struggled with this over and over and
| over. The tools are so hard to use it's tempting to make the
| version control process facilitate "git log" instead of the
| other way around, which is just absolutely insane. Obviously
| my co-workers should learn to use their damn tools like
| professionals, something something a poor craftsman, but
| honestly? This time the tools really are to blame.
| ryanisnan wrote:
| I think the non-editable nature of commit messages is precisely
| the benefit though. Yes, you can't really modify them post-hoc,
| but being able to step through a code base's history can be
| really illuminating.
| masklinn wrote:
| > I think the disadvantage with this style of documentation is
| you can't really alter the commit message after it's written.
|
| That is not a disadvantage. The commit is a historical record,
| if I come back to that commit 3 years later I want to know its
| purpose in the context it was in, I don't want a whitewashed
| history.
|
| > Compare that with documentation stored in a .md file, or even
| a Wiki or even Confluence. My colleague can write something and
| if I see a way to improve it I can go ahead and do that, and
| other colleagues can improve on what I've written.
|
| That's like comparing a bicycle and a goose.
|
| > But I also myself find it tempting to describing the design
| of a particular component when I commit that component, and
| that's something I now avoid.
|
| That's a shame. Knowing the considerations (or lack thereof)
| and tradeoffs at time of creation are often useful to
| understand defects, either in the original, or in evolutions,
| or in changes of use case.
|
| > Will the commit documentation just describe the differences?
|
| Yeees?
|
| > Then in order for a new team member to find out how the
| system works by reading the documentation they've got to read
| multiple commit messages and "merge" them in their head.
|
| No, for that you maintain a separate "current" documentation,
| which does not need to cover implementation tradeoffs, or that
| the original was written under time crunch, or whatever.
| 20after4 wrote:
| I really love documentation that lives in the same repo with
| the code. My favorite is a .md file for every module, class
| or component. Some mixture of inline code docs and standalone
| docs is probably ideal. But docs as markdown that don't
| require some compile step to build the documentation, and
| doesn't require opening a browser to view them, is just so
| much better, IMO, compared to any sort of external docs like
| a wiki or html on a server somewhere that gets re-generated
| by a CI job.
| thrdbndndn wrote:
| > That is not a disadvantage. The commit is a historical
| record
|
| OP's point is that, while commit message is indeed a
| historical record, documentation isn't (or shouldn't).
|
| If you double commit message as documentation, it would cause
| issues like wrong information confusing or misleading future
| readers because it's non-editable.
| Sprocklem wrote:
| Crucially, however, the commit message is not documentation
| of the code, which _would_ need to be changed and updated.
| Instead, it is documentation of the change, describing the
| reason for the change, what the code does to achieve that,
| and, if relevant, why you chose that solution. It provides
| necessary context to the already immutable diff and
| therefore need not be mutable itself.
| twosdai wrote:
| Sucks when you mess up in your commit message though and
| don't type the right thing.
| dllthomas wrote:
| > you can't really alter the commit message after it's written
|
| You can append with git notes, though on a message that long I
| expect they're unlikely to be noticed.
| goku12 wrote:
| Commit messages aren't a replacement for source documentation.
| The latter contains information relevant to the tree. Commit
| messages are transient information (historical info as someone
| put it). For example, an update caused by outdated dependency.
| Or the tests done to diagnose a bug.
| kelnos wrote:
| A commit message isn't documentation that should be updated as
| things evolve. It's a historical record of a single change.
| Sure, if you later realize you forgot to put an important
| detail there, that's a shame. But overall I think it's actually
| important that they can never change.
| tehnub wrote:
| I know this isn't a great solution, but GitHub does let you
| write comments on individual commits. You could add whatever
| addendums you want there.
| keybored wrote:
| I have seldom run into this being a problem.
|
| The context of a commit message is that someone took some
| minutes to explain what the context of the change is. Using
| their current understanding. Explain the problem. Lay out the
| _assumptions_. Given three paragraphs or so it will help
| _immensely_ to figure out how or why something you /them
| thought was the case was in fact _wrong_ when the message was
| written.
|
| _That_ is documentation in itself.
|
| And if you make straightforward mistakes like a typo in an
| issue key in the message and you _really_ care: you can make a
| note of it on the commit with git notes.
|
| > Compare that with documentation stored in a .md file, or even
| a Wiki or even Confluence.
|
| I don't want to access a remote wiki for every little code
| context (certainly not Conf.). The code is just _right there_.
| Comments /Doc comments/commit messages are mostly enough for
| that.
| fusslo wrote:
| great commits are great. This is fantastic
|
| As an aside, I'm tired of documenting:
|
| - in code
|
| - in commits
|
| - in jira
|
| - in confluence
|
| - in daily standups
|
| - in release notes
| marcosdumay wrote:
| The code and commit documentation are about different things.
| One is about what this thing is, the other is about what is
| changing.
|
| But then, jira is about what is changing, confluence is about
| what is changing, standups are about what is changing (oh, but
| this is doing them wrong), and release notes are about what is
| changing. So your complaint is completely reasonable, just the
| first item shouldn't be there.
| fusslo wrote:
| I dont think Ive worked at a company that used commit
| messages to record what is changing.
|
| Im not saying that I am disagreeing with you on that point.
| I'm just sharing my experience
|
| We tend to rely on the diff and PR for the 'what is changing'
|
| The PR doesnt list the commit messages anyway, just the last
| commit message and the PR description
|
| We add links to jira/confluence a lot in code to give direct
| access to the dev. Commits are tied to features or bugfixes
|
| So effectively commit messages are not useful anymore
|
| The only one that might be useful is the merge commit message
|
| Again, not disagreeing, just complaining lol
| GuB-42 wrote:
| You also get what is changing by doing "git diff", and often,
| it is self explanatory, especially if you have already
| commented in code why you did what you did.
|
| For example: - code: MAX_SIZE=1024 // maximum
| size the backend supports - commit: limit the size to
| 1024, as it is the maximum the backend supports - jira:
| fixed the problem by limiting the size to 1024, as it is the
| maximum the backend supports - confluence: do not
| exceed 1024, as it is the maximum size the backend supports
| - standup: I set the maximum size to 1024, as it is the
| maximum the backend supports - release note: Maximum
| size set to 1024, as it is the maximum the backend supports
|
| This is all redundant. I used a simple example for the sake
| of brevity, and one-liners are reasonable in every case, but
| the problem is when you are expected to write a wall of text
| every time, when in reality, there is everything you need in
| the code.
| kelnos wrote:
| I'm generally wary of code comments. They tend to rot;
| people change the code around them but then forget to
| update the comments. They also take up valuable screen real
| estate. I'd mostly rather be reading code than comments,
| and I can see more context when there are fewer comments.
|
| If a comment truly is necessary, it should explain why the
| code is doing something tricky, unusual, or unexpected.
|
| In your particular example, that comment is superfluous;
| the constant should just be called MAX_SUPPORTED_SIZE, or
| something similar, that describes it better and makes the
| comment redundant and unnecessary.
|
| Otherwise I agree; there's so much redundancy in our work,
| it's silly...
| fusslo wrote:
| As someone who's been 'the next guy' to people who share
| your opinion: I really disagree with your opinion
| Sohcahtoa82 wrote:
| - in Sharepoint
|
| - in some random Google Doc owned by one person that has to
| give permission to each individual who needs to read it, even
| though it's something the entire Engineering department should
| have access to.
|
| - in a GitHub Wiki that nobody even realizes exists
|
| - in a separate git repo that exists for just documentation,
| but nobody has checked anything into for 2 years
| fusslo wrote:
| sometimes I wonder: If I didn't need to update 6 things, get
| approval from two colleagues, and justify the time to a scrum
| master watching how many tasks I complete every 2 weeks...
| would I write more meaningful documentation?
| yura wrote:
| - in code: code-level context
|
| - in commits: changeset-level context
|
| - in jira: if you need to provide changeset-level context,
| point them to the MR/commit log
|
| - in confluence: high-level documentation
|
| - in daily standups: status update; if you need to provide
| changeset-level context, point them to the MR/commit log
|
| - in release notes: generate automatically from commit log
|
| IMO duplication in documentation should be treated the same as
| in code - it should be avoided as much as possible.
| rpsw wrote:
| Overall agree with the sentiment, but I would add a more specific
| Bottom Line Up Front (BLUF) such as: "Fix test issues caused by
| non-breaking space character \xa0".
|
| Tells me exactly what the problem was straight away, but I'm
| still free to choose to read more if I want to know more.
| nextaccountic wrote:
| I love this concept. I always begin messages with the most
| actionable or important thing at the top, and the rest that
| follows is the context. Respect the time of others and don't
| bury the lede
| SamuelAdams wrote:
| You see this all the time in business proposals. Executive
| summary at the top, typically 2-3 paragraphs max. Manager
| summary, 1-2 pages. Engineer detailed overview, 3-10 pages.
| Anything else is an addendum.
| master-lincoln wrote:
| This would be my ideal commit message as well. The rest of the
| commit body in the article is just how it was discovered. I
| don't think describing how one works belongs into a git commit
| message. Your message tells me why and which change was made,
| that's enough to me.
| Anon1096 wrote:
| Yep this message is way better. And honestly, looking at the
| diff in github it is pretty obvious to me what has changed (and
| why really, since the only reason for a changeset to have a
| diff look identical is that non-visible characters have been
| added or removed).
|
| So all I'd require is a good main message for history-search
| purposes. A short story about how you went to Narnia and came
| back to find the root cause of a bug isn't really relevant imo
| but I'm also not against writing it if you just want to vent in
| a PR description/commit's extended message.
| andrewfromx wrote:
| 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.
| karmajunkie wrote:
| I've been using opencommit[1] and have been pretty happy with
| the summaries its generating. I usually add a one liner at the
| top to summarize the reason for the PR but it saves me a lot of
| typing documenting what was actually done at a high level.
|
| [1] https://github.com/di-sukharev/opencommit
| lexicality wrote:
| that's a great idea but you can make it even more efficient
| head -c50 </dev/urandom | xxd -p -u | git commit -a -F -
|
| 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!
| andrewfromx wrote:
| 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.
| WalterBright wrote:
| At the DLF, our pull requests are usually accompanied by a link
| to the bugzilla entry, which usually have a detailed explanation.
|
| P.S. Having multiple Unicode values that exhibit identically when
| displayed are a huge veer-into-the-ditch mistake. I.e. the notion
| that code points should have semantic value is simply wrong.
| boolemancer wrote:
| > P.S. Having multiple Unicode values that exhibit identically
| when displayed are a huge veer-into-the-ditch mistake. I.e. the
| notion that code points should have semantic value is simply
| wrong.
|
| Should a cyrillic `a` and a latin `a` have the same code point?
|
| If they did then there's no consistent way to group those two
| alphabets, one or the other would end up with letters outside
| it's main grouping.
|
| And what happens if the shapes of those two characters divege
| over time? Do you have a breaking change to introduce a new
| code point for one of the languages, or do you just make it
| impossible to have a font that can be used for both latin and
| cyrillic at the same time?
|
| This isn't just a theoretical problem, by the way. There are
| characters in Chinese and Japanese that share a code point but
| the shapes of the characters aren't the same in the two
| languages.
| kelnos wrote:
| > _our pull requests are usually accompanied by a link to the
| bugzilla entry, which usually have a detailed explanation._
|
| This practice annoys me quite a bit, actually. Well, if there
| is a bug tracker issue, of course, definitely link to it in the
| commit message. But that should provide extra, optional
| information; everything I reasonably need to understand the
| change should still be in the commit message. I don't want to
| have to chase down the information in an external system, a
| system which may not even be running anymore... and of course
| we all know that when systems get shut down, of course they get
| backed up and archived and made accessible properly every
| time... right.
| ajuc wrote:
| I agree commit messages are the most important form of
| documentation.
|
| But I disagree about the format. I prefer commit messages like:
| JIRA-123 one-line 80-char-at-most description Long
| description if needed (but preferably keep it in JIRA).
| masklinn wrote:
| > but preferably keep it in JIRA
|
| Jira is an additional indirection to a tool you will (not
| might) eventually lose. I've seen commits which had lived
| through 3 VCS transitions.
|
| Not only that, but a lot of information is often considered
| undesirable on tickets.
| computerfriend wrote:
| Deeply strange to me that you can think that they're the "most
| important form of documentation" and then propose to put the
| documentation elsewhere.
| ajuc wrote:
| JIRA contains more context than you can put in even most
| elaborate comment. For example links to duplicates, test
| cases, screenshots, core dumps, discussion with
| testers/customers, etc. And it's updated over time.
|
| Would you change the commit message if a tester noticed
| something about your explanation of the bug was wrong but the
| fix still works?
|
| Additionally the context is already there in the JIRA,
| retyping it in detail in a different format into the commit
| message is more friction for little benefit.
| bhasi wrote:
| For great commit messages, just browse the git history of the
| Linux kernel where this is the standard.
|
| The first line always mentions the subsystem affected by the
| change, followed by a one-line imperative-mood summary of the
| change. Subsequently, three questions are answered in as much
| detail as possible:
|
| 1. What is the current behaviour? 2. What led to this change? 3.
| What is the new behaviour after applying this change?
|
| Example:
|
| "Currently, code does X. When running test case T, unexpected
| behaviour U was observed. This is because of reason R. Fix this
| by doing F."
| chjj wrote:
| Just an aside: is there a vim syntax command to highlight weird
| unicode whitespace as an error?
|
| Something like: syn match unicodeWhitespace
| /[list of unicode whitespace]/ hi def link
| unicodeWhitespace Error
| a_e_k wrote:
| I wouldn't know about the Vim equivalent, but I wrote this in
| my Emacs config long ago: (defun find-non-
| ascii () "Find and show all of the non-ascii
| characters." (interactive) (occur
| "[[:nonascii:]]"))
|
| It has proved quite useful on occasion.
|
| (Yes, I could just invoke Occur directly, but I can never quite
| remember the regexp character class and syntax here.)
| chjj wrote:
| No worries. I managed to whip something up:
| autocmd BufWinEnter * match ErrorMsg
| /[\xa0\u1680\u2000-\u200a\u202f\u205f\u3000]/
| xigoi wrote:
| For non-breaking spaces specifically, there is :help 'list'.
| gtirloni wrote:
| Great commit indeed. lots of context information. that's gold.
|
| The worst I've seen are dozens of tiny commits pushed to the
| master branch directly. If you want to find out what took to
| implement a feature, good luck.
|
| I'm a fan of tiny commits during code review but afterwards I
| prefer to squash everything in a functionally relevant commit. It
| makes git archeology much easier.
| schacon wrote:
| 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" problem. Everything they talk about in this
| article is what is great about the _rest_ of the commit message,
| which, given modern tools, is _almost never_ seen by anyone.
|
| The main problem is that Git was built so that the commit message
| is the _email body_, meant to be read by everyone in the project.
| But for better or worse, that is not generally the role of this
| text today. Almost nobody ever sees it. Unless it's discussed in
| a bunch of patch series over a mailing list, nobody reads
| anything other than the first 50 chars of the headline. It's
| actively difficult to do, by nearly every tool built around the
| Git ecosystem.
|
| Even if you're _very good_ at Git, finding the correct invocation
| of "git blame" (is it "-w -C -C -C"? Or just _two_ dash C's?) to
| even find the right messages that are relevant to the code blocks
| you care about is not widely known and even if you find them,
| still only show the first line. Then you need to "git show" the
| identified commit SHA to get this long form message. There is
| just no good way to find this information, even if it's well
| written.
|
| This is one of my biggest complaints with Git (or, indeed, any
| VCS before it), and I think why people just don't care much about
| good commit messages. It's just not easy to get this data back
| once it's written.
|
| If you want an example of this, search through the Git project's
| history. Run a blame on any file. It's _so hard_ to figure out a
| story of any function implementation in any file, but the commit
| messages are _pristine_. Paragraphs and paragraphs of high
| quality explanation for almost every single commit. Look at any
| single commit that Jeff King has done for the last decade.
| Hundreds of hours of amazing documentation from a true genius
| that almost nobody will ever appreciate. It's horrifying.
|
| I don't know exactly what the answer is, but the sad truth of Git
| is that writing amazing documentation via commit message, for
| most communities, is almost entirely a waste of time. It's just
| too difficult to find them.
| codemac wrote:
| 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 later.
| schacon wrote:
| 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 even if there are _amazing_
| commit messages.
|
| Like say you are trying to determine why a 10 line function
| is the way that it is. You blame it. Not even with the
| stupid-simple GitHub UI that _I_ originally wrote, but with
| the more expensive CLI interface that follows renames and
| ignores whitespace changes, etc. Now you get a list of SHAs
| of commits and the first 50 chars of commit messages for each
| line for the last modifications, etc. How do you even stitch
| those messages into a useful story (in order) to tell you how
| that function evolved to what it is now and why?
| cesarb wrote:
| It might depend on which tools you're using. When I'm doing
| historical research for how a function evolved, I normally
| run "gitk" on the file, and walk through the commits; the
| full commit message is shown together with each diff to the
| file. It used to be even better in the past, when gitk
| showed the full commit diff, instead of the diff to just
| the file I passed on the command line, but "git show" on
| the commit hash (or another gitk which is not filtered to a
| path) is good enough.
| lazyasciiart wrote:
| P4V (Perforce Visual Client) is amazing for visual
| historical research. I haven't seen a git tool like it, but
| I'd love one. https://www.perforce.com/video-
| tutorials/vcs/using-time-laps...
| somerandomqaguy wrote:
| 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.
| keybored wrote:
| > I think it's optimized for discussions before
| integration, which is largely what PR descriptions and
| comments are largely used for now.
|
| As a GitHub co-founder, whose fault is that? I have seen
| many great PR descriptions on GitHub that never make their
| way into the final inclusion in the main/master git
| history.
|
| Meanwhile the git project links every commit to the message
| id whence the original patch (for many years now--not the
| whole history). Which will be available as long as the
| email archives are out there somewhere.
|
| And the commit messages get reviewed into a good shape.
| Something that I've never seen anyone do on GitHub.
| neilkk wrote:
| But Github and similar tools actually solved this problem
| where Git failed to do so. Nowadays people have a setup
| with Github or bitbucket where they can navigate from a
| piece of code right to the pull request, where they can
| read the code review discussion, see the build log, reach
| linked resources like the Jira, etc.
| mtrower wrote:
| > I think it's optimized for discussions before
| integration, which is largely what PR descriptions and
| comments are largely used for now.
|
| This isn't even a git concept though; it's something that
| was tacked on top of it. What you seem to be saying here is
| that a third-party tool building on top of git spawned a
| social movement that moved this layer up a level. Not every
| project uses github or a github workflow.
|
| > I think it's optimized for discussions before integration
|
| It's optimized for discussion of the purpose of the code
| unit in question. That discussion can be useful before
| integration; but pre-integration discussion can happen any
| way you like. PR discussions work, e-mails on mailing lists
| work. Face-to-face discussion works.
|
| The real value (for me, I guess; apparently you just don't
| see it that way) is explaining the purpose (and possibly
| circumstances) of the commit, after the fact, when I'm
| looking at it for some reason or other. Not finding the
| commit, but explaining it once I'm there. A well-written
| commit message can be absolutely priceless.
|
| Maybe this last point should go in a top-level response to
| your original comment, but I'm already here, so I'll just
| say it here. Saying that commit messages are terrible
| because only short-messages (the "subject line") are shown
| by default, seems to me about the same as saying e-mail
| bodies are useless for the same reason, or that file
| contents are terrible because `find` only lists file names
| by default. You 'have' to collapse by default, or you'd
| drown in a sea of commit messages anytime you tried to list
| _anything_.
|
| > Like say you are trying to determine why a 10 line
| function is the way that it is. You blame it. Not even with
| the stupid-simple GitHub UI that _I_ originally wrote, but
| with the more expensive CLI interface that follows renames
| and ignores whitespace changes, etc. Now you get a list of
| SHAs of commits and the first 50 chars of commit messages
| for each line for the last modifications, etc. How do you
| even stitch those messages into a useful story (in order)
| to tell you how that function evolved to what it is now and
| why?
|
| Okay, I hear you, this is not the most ergonomic procedure
| to one-off. But seriously, you have the SHA commits. If you
| need to do this often, write a tool that takes those SHA
| commits, orders them based on log order (or chronological
| order, w/e, pick an ordering mechanism), and prints out
| whatever information is interesting to you. A simple
| display that can expand/collapse full messages, diffs, etc.
| would probably do nicely. It can be a GUI tool, a CLI tool
| (menu-driven, maybe); whatever works for you. This should
| not be a big deal to write for the common case, and if you
| think it's that critical to the community, publish it.
| lanstin wrote:
| Till the team you are handing off the code to just copies the
| files and commits into a fresh new repo without any of the
| history. I had this happen once to a server I wrote, and then
| like 2 years later the new team comes and asks me if I knew
| of the server, and I'm like "I wrote it" and then they are
| all confused.
| tcoff91 wrote:
| Many editors have great git blame integration that makes these
| messages quite accessible.
|
| It's really easy in emacs with magit to view commit messages
| from git blame view.
|
| I believe vim, vscode, and jetbrains IDEs all make this simple.
| nijave wrote:
| Yeah, a lot of these also have Github and ticket tracker
| (Jira, etc) integration so they'll also pull in context from
| those, too
|
| Most of the stuff I work on uses merge commits on Github so
| you can just click the PR # in the merge commit message and
| arrive at the PR, browse through commit messages, discussion,
| etc
| cerved wrote:
| Using vim-fugitive it's :Git blame %
| ep103 wrote:
| 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 engineers we want to
| make tools to cause people to fall into the pit of success. So,
| improving this part of git makes sense.
|
| On the other hand, just do your damn job. If a coworker doesn't
| understand a code change, because they didn't bother to read
| the commit message, they're a bad developer. If they didn't
| write a git commit message because "no one is going to read it
| anyway", they're a lazy engineer. These things aren't excuses,
| they're incompetence, and not everything needs to cater to the
| least competent people in our profession.
| herrkanin wrote:
| If writing good commit messages isn't specifically defined as
| part of your job, why would you waste business hours writing
| commit messages that are beyond what is expected of you and
| frankly useless since nobody would ever read it anyway?
| groestl wrote:
| I'd do it for CYA purposes in case smt goes wrong and my
| commit is involved.
| DarkNova6 wrote:
| In my company we norm the titles of MRs, give it a ticket
| number and squash it all. If you can't concisely describe
| what you did you need to split your MR.
|
| Helps with reviewing as well as blaming.
| erik_seaberg wrote:
| Writing good commit messages is part of your job in the
| sense that no reviewer should be approving anything without
| them, knowing that you may or may not be available if it
| breaks next year at 3 AM.
| kaashif wrote:
| I put that kind of thing in the pull request, since
| that's where the review happens. Every commit links back
| to a pull request, and people actually do refer back to
| it. Writing good documentation there is part of the job.
|
| No-one's going to ALSO write commit messages that no-one
| will see.
| wnoise wrote:
| The git history will last longer than the platform
| hosting the PR.
| erik_seaberg wrote:
| Not only is "git log" always up, I can also skim it
| without opening a hundred browser tabs.
| cozzyd wrote:
| pull requests don't live in the repository (as far as I
| can tell...) and require you to use whatever online
| interface creates them.
|
| Not sure whey e.g. Github Pull request merges don't
| include the entire pull request description in the merge
| commit message.
| ickyforce wrote:
| In my opinion PR/changeset description is exactly what
| should be in the commit description. In cases were we had 1
| commit per PR (i.e. squashing before merging) just copying
| the PR description into merge commit worked really well -
| the goal for a PR description and a commit is essentially
| the same.
|
| I wish github allowed to make the copying automatic and
| ensure that it happens (it doesn't, unfortunately).
|
| If someone wants to learn the full history - the remarks
| during code review, perhaps all the WIP commits - they can
| read the PR/code review comments. I found it to be very
| rarely needed.
| arccy wrote:
| settings > allow squash merging > default commit message
| > pull request title and description
| sgerenser wrote:
| This is exactly how Microsoft Azure DevOps works when you
| enable the squash-on-merge behavior (which is how we used
| it while working at Microsoft). I thought this was
| completely logical and I'm surprised that GitHub can't be
| configured the same way.
|
| All of our commit messages were nice, long and detailed,
| with a link back to the PR if you really wanted to go
| back and see the individual commits and/or discussion
| that occurred on that PR. I think I only looked at
| individual commits maybe once or twice since they were
| usually useless in isolation (woops, WIP, fix typo,
| etc.).
| kriiuuu wrote:
| But if you don't cater to the worst on your team you are
| often viewed as the problem
| schacon wrote:
| I feel like it's not a question of "doing your damn job".
| It's a question of what value can you expect to get from a
| particular investment. If blame is your tool and every line
| happens to be changed from a different blame invocation (is
| it "-w", "-w -C", "-C -C -C", etc), how do you learn the
| story of this block of code best? Maybe you then need to read
| a story _per line_ of code. But that's not actually worst
| case. Maybe you need to drill down to the commit _before_
| that because the last change isn't semantically important.
| Maybe the one before that, etc. How many commits that touch
| those lines significantly do you need to research and read
| amazingly well written commit messages before you totally
| understand the context of this particular block of code?
| Eji1700 wrote:
| Coding is a really interesting field in how quickly it's
| developed, and I think there's a lot of people who assume
| their environment is the only environment and it should be
| that way for everyone.
|
| Spending time digging through commit messages when tooling
| and design makes it harder, not easier, is a risky
| proposition if it turns out it was all fucking useless and
| you didn't find anything worth reading and are now even
| farther behind. Either due to the quality of the messages
| or a lack of your ability on your end to find what you
| need.
|
| I'd love to work in the sort of environments these people
| seem to but it's just not been the case. I'm at a smaller
| company where I get to wear many hats, and
| coding/development is just one of them, but I know plenty
| of people at very large companies who also don't really do
| things like that because "putting in the effort" isn't
| rewarded as much as whatever arbitrary metric they're
| graded on.
| c0pium wrote:
| Git visualization isn't git's job, providing primitives
| like blame for git visualizers is. If you use VSCode with
| gitlens (pycharm is similar), the exercise you just
| mentioned is trivial. Focus a line, get the correct blame.
| Click on that, view the commit history. Click from there,
| see the diff.
| Sohcahtoa82 wrote:
| > it never ceases to surprise me how often developer
| complaints stem from developers just not doing their damn
| job.
|
| One thing I learned is that any forum that appeals to
| software engineers will appeal to software engineers _of all
| skill levels_ , from the guy that did a 6 week coding camp
| because he heard SWEs make a lot of money but didn't really
| learn anything but thinks he's an expert now, to geniuses
| with 10+ years experience.
|
| For every comment from someone who really knows what they're
| doing, there's one from someone that really doesn't.
| josephg wrote:
| Yep. This is one of the big problems with online
| communities. When someone makes a bold statement, I have no
| idea if they're a grizzled engineer with grizzled, hard
| earned engineering opinions, or some kid fresh out of a
| coding bootcamp who thinks they're all that. In person, I'd
| treat those two people incredibly differently. Online? It's
| impossible to spot the difference.
|
| It doesn't help that we all think of ourselves as
| programmers, even though people in our industry have a wide
| range of jobs. Someone working at a feature factory banging
| out websites and mobile apps has a very different job from
| someone slowly puzzling out a new cryptography algorithm or
| debugging a kernel driver. You can tell they're different
| jobs because excelling in those roles takes different
| skills. In the first case, you want to know your domain
| backwards, have great social skills and work consistently.
| In the later cases, you need deep CS knowledge, patience
| and insight. It's different.
|
| Who is this site for? What does everyone do for your job?
| It's all quite unclear.
| teaearlgraycold wrote:
| Once I started interviewing - mind you, interviewing
| candidates that already got through several filters
| before getting in front of me - I realized how mediocre
| the average engineer is. Should it then follow that the
| average engineering opinion online is mediocre?
| arccy wrote:
| pretty much yes, even here you see a lot of
| overconfidently mediocre takes
| teaearlgraycold wrote:
| It's important to know how to stick to your course in the
| face of bad advice.
| JadeNB wrote:
| > Yep. This is one of the big problems with online
| communities. When someone makes a bold statement, I have
| no idea if they're a grizzled engineer with grizzled,
| hard earned engineering opinions, or some kid fresh out
| of a coding bootcamp who thinks they're all that. In
| person, I'd treat those two people incredibly
| differently. Online? It's impossible to spot the
| difference.
|
| I know there are limits to this, but isn't that a good
| thing, too? It's all too easy to treat a newbie as if
| they can't possibly have useful things to offer to the
| community; being forced to treat all comments equally,
| without being able to fall back on the crutch of
| reputation, arguably forces one to read and engage more
| deeply with the content, and offers the chance to surface
| the occasional genuinely valuable contribution from a
| newbie (or, for that matter, to avoid letting someone get
| away with an ill considered or overbroad statement just
| because they have such a big reputation that people are
| too afraid to stand up to them).
| Sohcahtoa82 wrote:
| True, but occasionally a newbie offers a solution to a
| problem and rejects the rejection when people try to tell
| them why their solution won't work.
|
| For example, several years ago here on HN, during a
| thread about cryptography, someone admitted to not
| knowing much about cryptography, but offered one-time
| pads as a solution to the weaknesses of PKI. I tried to
| tell them that OTP solve a different problem that is
| unrelated to PKI, but they wanted nothing of it. They
| claimed that my response was purely emotional and that
| just because I knew more than them about cryptography
| doesn't automatically make them wrong. When I tried the
| Socratic Method to lead them towards an understanding of
| why they were wrong, they accused me of being
| condescending and said that I should answer my own
| questions.
|
| If I see a bold claim that I have a hard time believing,
| then I'll ask follow-up questions. But when someone makes
| a bold claim that is just factually incorrect, _while
| admitting they don 't know much_, and then get upset when
| someone tells them why it's incorrect, then that's just
| plain frustrating.
| eschneider wrote:
| 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.
| ChrisMarshallNY wrote:
| 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/
| mixmastamyk wrote:
| 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.
| _Algernon_ wrote:
| This entire thread is making me feel like I'm taking a
| crazy pill.
|
| A simple git log is considered "esoteric" these days? No
| extra command line arguments are required to read the
| entire commit message. If so software "engineering" is
| truly a dead discipline. I guess the "move fast and break
| things" crowd have taken over.
| ChrisMarshallNY wrote:
| Not sure why you're attacking me. I don't remember saying
| anything offensive.
|
| Anyway, I've _never_ been a fan of "moving fast and
| breaking."
|
| Might want to give that blog entry I linked, a read.
| mixmastamyk wrote:
| Never worked with other people? Git as a thing is off the
| table.
|
| Which commit? Where, how? Pro{gram,ject,duct}M, SME, QA,
| or user wants to know why? Do they even have a login to
| the systems they'd need? Is there search so they could
| find it themselves when you quit?
|
| Or you could send them a link to the docs.
| sethammons wrote:
| Any system where the proposed solution is "be better" without
| an outline of "and here is how" and some method of
| enforcement is doomed to fail.
|
| Checklists, build checks, linters, tests, SLOs, post incident
| responses, follow up tickets, etc all serve to unload "be a
| better software developer" into actual systems and processes
| that can continuously enable the better behavior.
|
| Simply stating "do a better job" wont work as organizations
| scale. Related, you can expect what you inspect.
| keybored wrote:
| There were two hands in that comment (on the one hand/the
| other). One hand said that Git and other tools should be
| better. Only the other hand said to _be better_.
| lanstin wrote:
| I'd hate to say that laziness makes a person an incompetent
| developer. Often my problems stem from an excess of sincere
| hard work and rather than from laziness.
| qez2 wrote:
| > If they didn't write a git commit message because "no one
| is going to read it anyway", they're a lazy engineer.
|
| If an engineer spends an hour writing a commit message that
| no one reads, that's an unproductive engineer, compared to
| where they should be.
|
| I have to admit, I am lazy. I don't spread seeds by hand; I
| use a tractor. I don't swim across the ocean; I use an air
| plane. Likewise, I don't write documentation in commit
| messages; I write documentation in PR descriptions, READMEs,
| and official document sources. You got me, I'm incompetent.
|
| My "job" is to write software, not follow some arbitrary
| "pure" practices.
|
| > If a coworker doesn't understand a code change, because
| they didn't bother to read the commit message
|
| And I would argue we shouldn't cater to developers who make
| documentation difficult to access for everyone else by hiding
| it where only crappy tools can reach it.
| mtrower wrote:
| > If an engineer spends an hour writing a commit message
| that no one reads, that's an unproductive engineer,
| compared to where they should be.
|
| Okay, maybe don't spend an hour. It would take a special
| kind of commit to need more than a few minutes writing a
| decent commit message.
|
| > And I would argue we shouldn't cater to developers who
| make documentation difficult to access for everyone else by
| hiding it where only crappy tools can reach it.
|
| Yeah. Like web browsers. And PDF viewers.
|
| The non-caustic point here is that clearly different people
| have different ideas about what is accessible.
| Cthulhu_ wrote:
| 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 chapters, I learned
| how to google and instead of reading everything, just find
| what I need. I never went in-depth with reading because...
| it's mostly useless knowledge that quickly becomes outdated.
| theamk wrote:
| Nah, we have documentation with a clear starting point -
| there is index page with most common topics, "new user"
| page with links to what new user should read, and some
| error messages actually contain wiki links to pages with
| instructions.
|
| And yet we still have people who don't read documentation.
| mostlylurks wrote:
| 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").
| lazide wrote:
| Counter point - Engineering systems which require constant
| overriding of basic human nature therefore requiring making
| significant effort on the regular to avoid mistakes is bad
| engineering.
| bastardoperator wrote:
| Why would I waste time reading this paragraphs long commit
| message when I can look at a diff and a 40 character headline
| and completely understand the issue? You think it's lazy, I
| think this is wasteful. Personally I don't need an epic story
| about making a one character change because your editor isn't
| configured to catch gremlins... it's just not that
| interesting.
| c0pium wrote:
| Because you don't actually understand the subtleties of the
| side effects of that 40-character change and building
| intuition about it takes a paragraph.
|
| It's all fun and games until your codebase is >1,000,000
| loc.
| nonethewiser wrote:
| The "just do your damn job" retort presupposes that their job
| is to read the entire body of every git commit. That's the
| question - you can't just presuppose it.
| mb7733 wrote:
| Well, `git` is still the primary way I interact with a git
| repository, and `git log` shows the entire commit message by
| default. So I don't run into this problem.
|
| If some "modern" git frontend is only capable of displaying the
| first line of a commit message, then this is a problem with
| that tool, not git itself.
|
| (I'm also not convinced this is a limitation of all modern
| tooling...)
| schacon wrote:
| I can't tell if this is engaging with trolls or not, but I
| can't imagine that all of your interactions with your
| codebase are via `git log` with no other flags. Even the with
| the normal Git CLI that most of us use daily, most of us use
| `--oneline` or whatever to simplify useful calculations and
| visualizations like `--graph`, etc. But we're talking here
| mostly about code archeology, learning about the history of a
| block of code, so this comment seems somewhat ridiculous in
| that context.
| bee_rider wrote:
| Is it possible that you've been hit by
|
| https://xkcd.com/2501/
|
| ? git log | less /whatever
|
| Works OK for those of us who don't know any git flags.
| fl0ki wrote:
| The only sets of arguments I use to git log regularly:
|
| * `git log branch` because I want to cherrypick or
| checkout parts of another branch.
|
| * `git log --stat` because what files changed can be a
| big clue for what I'm looking for.
|
| * `git log -- dir1/ file1/` because I only care about
| commits to a certain part of the tree.
|
| Other than that, `git log` already provides so much
| information to /search or even `grep` through that I
| can't think of any other flags I use regularly, and if
| you don't use them regularly you forget them.
|
| The real GOAT that people are sleeping on is `git rebase
| --interactive` where you can go back and edit part of
| your branch to clean it up before rebasing or merging
| towards main. The cleaner the commits are, the more
| useful they become later for other tools like log, merge,
| rebase, cherry-pick, bisect, etc.
| mb7733 wrote:
| I don't know how my comment was understood to mean that I
| am unfamiliar with git. My point was that those of us
| that use the git CLI have no issues seeing the rest of a
| commit message besides the first line, and in fact this
| is the default.
| mb7733 wrote:
| > I can't imagine that all of your interactions with your
| codebase are via `git log` with no other flags.
|
| When did I say anything like that?
|
| My point is just that the `git log` command, by default,
| shows the full commit message. The same goes for `git
| show`. So a user of the git CLI will regularly see complete
| commit messages, unless they purposefully request a
| different format. So, it is not some inherit problem in git
| that the complete commit message is hard to find. That's
| just a limitation of certain Git frontends.
| keybored wrote:
| > I can't tell if this is engaging with trolls or not,
| [...] that most of us use daily, most of us use `--oneline`
|
| You speculate that someone who uses git log without listing
| (or complaining about) all their flags are a troll?
| TheRealPomax wrote:
| periodic reminder that `gitk` exists, and has come with git
| since... pretty much forever? If you're reading `git log`,
| you really owe it to yourself to run `gitk` at least once to
| see what you've been missing for over a decade now.
| tux1968 wrote:
| I never considered the idea that it was atypical, but I read
| full commit message text all the time. There are many different
| ways to drill down into a commit, and then read the entire
| commit once you know it's relevant. Even doing a simple git
| log, and then a searching for some keyword through every full
| commit message, can be useful.
| globular-toast wrote:
| This is a failure of GitHub etc. GitHub tries to dumb things
| down for users because I guess it's judged they can't reason
| with commit histories and this is one of the consequences. The
| mess in especially private GitHub repos is beyond belief
| sometimes.
|
| The thing is there's nowhere else for such documentation to go.
| It's not appropriate for a code comment. But we've got a whole
| generation of developers now who think git is GitHub and the
| only purpose of git is uploading changes to GitHub.
|
| Git sucks, but it sucks a lot less than everything else. But we
| need to go back to basics and understand what _version control_
| is actually for.
| dkarl wrote:
| > 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" problem.
|
| This is a feature, and a crucial one. No one would include
| fifty lines of explanation if everyone had to see it. It would
| be better to throw the information away than to inflict it on
| everyone who was scanning through the commit history looking
| for a particular change.
|
| Yet it is valuable information that only makes sense in the
| context of that change. There is nothing in the corrected
| version you can connect to the issue that was fixed. It's
| obnoxious to include comments about errors that have been
| removed, like this: # where civica
| QueryPayments calls are taking too long # use ASCII whitespace
|
| (This is ridiculous, but not unrealistic. I've seen code
| comments that said things like "# removed syntax error in
| invocation of query generator." This is what you get from
| programmers trying to juice their LOC stats.)
|
| The commit message is the right place for this kind of
| information, but most people reading the commit messages don't
| care. They're scanning through looking for something else, and
| all they need is a few words that tell them if this is the
| commit they're looking for. The person who needs to see the
| full story is the person who is interested in this change in
| particular. Maybe they found it by grepping the git log for
| "invalid byte sequence". Maybe they found it because they're
| looking at all the changes in that file, because some tooling
| that occasional modifies that file keeps messing it up. What
| matters is that if they have a special interest in that change,
| they have a way to see whatever information they committer felt
| was worth preserving, and the committer has a place to put that
| information where only someone with a special interest will see
| it.
| brabel wrote:
| > Even if you're _very good_ at Git, finding the correct
| invocation of "git blame" (is it "-w -C -C -C"? Or just _two_
| dash C's?) to even find the right messages
|
| I am terrible at git on the terminal, but with IntelliJ or
| emacs and magit, I can trivially find every commit ever to
| change a file, and easily navigate the commits to see every
| full commit message. It's not hard when you use a proper tool,
| and I have a feeling almost everyone has something like that?!
| Do you really try to stick with the git CLI and memorize
| hundreds of commands and flags?? Why?!
| schacon wrote:
| I don't know IntelliJ well, but I would be surprised if they
| did the rather expensive rename following that the multiple
| -C invocations did. Maybe someone can inform us here? GitHub
| definitely does not, but that is 100% my personal fault I
| assume.
| DarkNova6 wrote:
| 100% this
| bradjohnson wrote:
| IME git abstractions make it easy to read and navigate
| standard workflows, but incredibly difficult to repair issues
| that arise due to divergence of some kind or another because
| they are so opinionated.
|
| I use git 99% in the terminal, and 1% in some git tool for
| visualization, but I find that a lot of people use it in the
| opposite way and have problems working with others that use a
| very slightly different workflow. You don't need to memorize
| hundreds of commands and flags, honestly a dozen or two gets
| you to expert status in most respects.
| brabel wrote:
| I don't have any problem at all, when some really tricky
| stuff needs to be done, I google for a solution and run
| whatever command magic I find. If you don't need to google
| for git commands to do uncommon things, I imagine you have
| a huge capacity to memorize things, good for you, but most
| of us don't.
|
| I do understand how git works and could use the CLI most of
| the time if I wanted to, but there's exactly zero reason to
| do so. The GUIs offered by modern tools make it much more
| convenient and efficient to do things correctly. You really
| should't commit stuff without doing a careful review of the
| changes first, which is terrible to do in the terminal
| compared with using a GUI for that, for example.
| fragmede wrote:
| ChatGPT is really good at giving me the git invocation I
| need for weird complex stuff that doesn't come up
| everyday.
| mixmastamyk wrote:
| Terminal for repeatability, gitlab for visualization is a
| good combo I've found. Push your branch and a great diff
| is waiting for you.
| bigfatfrock wrote:
| I was mind blown reading this also - are we not programmers
| for the sake of laziness in the face of these kinds of
| "problems"? I have to hail Tim Pope for Fugitive.vim also.
| HAIL TIM POPE!
| winwhiz wrote:
| Really simple answer: Repeatability. I am not saying it is
| the only one right blessed answer, but if you really want to
| know why people haven't moved to pure GUI interfaces, imagine
| describing to someone how to add a new directory to their
| path. fleet $HOME/.config/fish.config #
| ADD this line somewhere set -x PATH /opt/git/bin $PATH
|
| Or: 1. Either hit WINDOWS-E and right click on This PC and
| select properties (it might be called something other than
| This PC if someone renamed it) or either press WINDOWS key or
| click Start or click the Windows icon (if you don't see them
| try mousing into a corner of your screen (typically bottom
| left) until they and the rest of the bar un-autohide) look
| for and click a gear symbol (should expand to say Settings if
| you hover), click System, on the left and the bottom you
| should see About. 2. Click the text Advanced system settings
| (on the right), look for a new window with a set of tabs, you
| want Advanced. Click the button Environment Variables. 3. In
| the top columnar box EITHER find a variable named Path,
| highlight and click button Edit, in a new window click button
| New, type '/opt/bin/git' in a text field that has appeared at
| the bottom list items, click OK OR click the button New, in a
| new window enter Path for Variable name and /opt/git/bin for
| Variable value, click OK (you shouldn't need to Browse
| Directory or Browse File). 4. Click OK button, click OK
| button, close Settings window.
| EdwardDiego wrote:
| Don't even need the set -x, can just use fish_add_path for
| convenience.
| marwis wrote:
| On Windows it's actually just:
|
| 1. Press Win key 2. Type env 3. Choose system or account
| winwhiz wrote:
| Thanks! This is what I was secretly hoping for. I am
| doing this a lot lately.
| keybored wrote:
| If the tool calls git(1) then it can show you the script
| that your actions produced. Magit has something like this
| but I've never used it for that (since I also use git(1))
| so I don't know if it captures the whole context/commands.
|
| I used a GUI frontend to R in a statistics course. Never
| needed to write R myself.
| Dylan16807 wrote:
| Have you ever heard of "abstraction"? People that actually
| use windows can handle opening the start menu as a single
| part of a step. There's no conscious checklist for how the
| UI can be customized.
|
| If you're going to make that into a complicated mess, then
| you absolutely do not get to assume the user understands
| "add this line somewhere" or has "fleet" installed and set
| up the way you expect.
| winwhiz wrote:
| Yes, I think we agree that abstraction is great (with or
| without "scair" quotes.) My point is that CLIs are valued
| as tools of explication, repeatable explication. I have
| actually used Window since 3.1. I cherry picked a
| particularly juicy example that I run into a lot.
|
| > If you're going to make that into a complicated mess,
| then you absolutely do not get to assume...
|
| As far as tooling goes the GP mentioned IntelliJ so I
| rewrote _code_ with _fleet_ , I could have easily have
| picked emacs or vim or bash or zsh or tcsh instead of
| fish and the complexity of interface would have remained
| static. I think HN formatting tools are partly to blame
| for the messiness but if you look at any quality set of
| docs describing a complicated computer interaction, to
| achieve the same level of repeatability as text-based,
| POSIXy interactions you are going to need a lot of screen
| shots and a few this or thats. WHICH is fine! Remember
| software engineering is about trade offs!
|
| EDIT: CLI allows for abstractions like $EDITOR and $SHELL
| gregmac wrote:
| Your fictional example is not a good comparison -- I just
| can't imagine the scenario where you need to explain to
| someone who doesn't know how to modify their path why they
| need to add something to it.
|
| For someone actually using git (and the CLI, at that) I'd
| expect to be able to say "oh, make sure git is in your
| path" and for them to understand how to check and set that,
| or at least be able to Google it and follow the
| instructions themselves. Likewise I'd ask something like
| "Can you cherry pick just that bug fix into a new PR so we
| can merge and deploy it today?", not give them a series of
| git CLI commands to paste in.
|
| My observation of git beginners is ones using CLI say
| things like "oh, I screwed up my repo and had to clone a
| new copy". Good GUIs don't easily cause this situation, and
| mostly let you see and fix what happens when you do some
| weird accidental merge or rebase or someone else has force-
| pushed.
| winwhiz wrote:
| Yeah, I think I conflated a git specific question from
| the GP and a more general CLI question, my bad.
|
| The argument can be made the interfacing with git is bad
| whether with mouse or with keyboard. My git secret weapon
| is to ask myself how do I make git do this thing that is
| easy in Subversion or Fossil and then I do that thing and
| I write it down so I can do it again in X number of
| months.
| mostlylurks wrote:
| I don't find it more difficult to use or remember commands
| for than remembering how to accomplish similar tasks in some
| GUI (especially if that GUI is emacs). And unlike most GUIs
| (emacs may be an exception), I can trust that my knowledge of
| the git CLI won't become out of date when my GUI tool
| inevitably undergoes a UI redesign of some sort.
|
| But more importantly, the CLI allows my typical workflow
| where I chain together a bunch of git (and other) commands in
| a row, allowing me to just type in, for instance, several
| different commits, their messages, and what files should go
| into each in one go without having to break my concentration
| by having to move around in some GUI between commits.
| Sprinkle in some stash manipulation and interactive rebases,
| compilation, and unit testing, and you'll really start to see
| how the CLI allows you to offload some of your working memory
| to your invocation in a way that a GUI just can't.
| js2 wrote:
| 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 that's of the form "bleh" or "add a
| thing" when the developer could have spent 60 second to write
| down why they did it.
|
| Nothing gives me more joy than to find a commit message (often
| my own) that explains in detail why something was done. A
| single good commit message can save me hours or days of work.
|
| Let me also just say, and this is a bit of shot: GitHub
| contributes to the problem of bad commit messages. If I'm
| lucky, folks have put some amount of detail in the PR
| description, but sadly that's not close at hand to the commit
| log. It's another tool I have to open. Usually though, the PR
| is just a link to Jira, so that's another degree of indirection
| I need to follow. Then the Jira is a link to a Slack
| conversation. And the Slack conversation probably links to a
| Google doc.
|
| As an industry, we're _terrible_ at documentation. But folks
| like Jeff King are fighting the good fight. At the end of the
| day, I don't think the problem is with the technology. I think
| it's a people problem. Folks perceive writing documentation as
| extra work, so they don't. There's no immediate value to it.
| The payoff comes days, weeks, or months later.
|
| Please, write good commit messages. Just spend a minute saying
| why you did something so that every commit isn't a damn
| Chesteron's fence exercise. Put it in the commit message where
| I can easily find it. Your future self and I thank you.
|
| Edit to add: I didn't address your argument, that commit
| messages are too hard to find.
|
| First, I don't find this to be true. I rarely have trouble
| following the history of a line of code, a function, or a file.
|
| Second, commit messages have value at the time they are written
| even if they are never seen again. I find that writing a good
| commit message helps ensure that I've written in code what I've
| intended to (I often view the diff while writing the commit
| message) and they have value to the people reviewing my code.
| neilkk wrote:
| 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 character is an ascii space, so the whole
| commit message is just a blog entry in the wrong place.
|
| It would have made sense to just put a comment at the top of
| the file saying "make sure encoding is whatever".
| Dylan16807 wrote:
| > 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.
| tehnub wrote:
| 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.
|
| Well what about this example: I removed a few lines of code
| and explained in the commit message why I thought it was
| correct to do that. If somebody (possibly me) comes looking
| for that code and realizes it's not there, they'll be much
| happier to see some sort of explanation rather than a
| "removed lines" message.
|
| Regarding commenting in the code vs. in the commit message,
| sometimes I copy-paste my explanatory comment if there is
| one into my commit message.
| neilkk wrote:
| Right. You've given an example of exactly what I said was
| the only reasonable use case for detailed info in the
| commit message: someone in the future will need to know
| the history of that particular piece of code. It seems
| like the point of your specific example is to say 'in
| some cases you might want to know the history of a _gap_
| '. Fine. That seems like a nitpick to me.
|
| No one in the future will need to know the history of a
| particular ascii encoded blank space (among a whole file
| of ASCII encoded blank spaces). Anyone who needs the
| general info that the file needs to be ascii will be
| helped by it being somewhere else, as opposed to in a
| random commit message.
| js2 wrote:
| Sometimes a comment is appropriate. Sometimes a commit
| message is appropriate. Sometimes I need both. Often when
| dealing with legacy code I find neither. I'd be happy with
| either.
|
| A commit message lets me tell a short story about a change
| that touches multiple locations in the code base. Maybe no
| one part of the change is all that tricky.
|
| A commit message also allows me to explain why I'm making
| the change, whereas a comment may explain why the code is
| the way it is.
|
| Commit messages and comments have overlapping use cases,
| but the Venn diagram is not a circle.
|
| $0.02.
| cerved wrote:
| The example in the blog post would be a much better example
| if some kind of test or linting step was added to catch
| these white-space errors, to explain the need for catching
| such errors.
|
| Pro tip, you can write both comments and commit messages.
| zaptheimpaler wrote:
| I feel half vindicated about my rant a few weeks ago[1] arguing
| that we should make commit messages as long as we like instead
| of the stupid 50 character or whatever limit. If enough people
| do that, maybe tools like GH will stop wrapping the message by
| default. Even if not, atleast the first line is usually easy to
| see in most tools by hovering over it or something.
|
| [1] https://news.ycombinator.com/item?id=38831282
| cerved wrote:
| Presumably you're referring to commit subjects.
|
| And no, they should absolutely not be as long as you like. It
| breaks things
| goku12 wrote:
| I don't know how it's for everyone else, but I do value the
| body of the commits from others. It's true that I see only the
| subject line for most commits. But I eventually read the full
| body of commits I'm interested in. Honestly, it's frustrating
| when commit messages don't carry enough context. Sometimes that
| context fits in the subject line. For others, I expect an
| elaborate body.
| madsbuch wrote:
| On my work I make 1-15 commits a day. If I have to spend
| thought cycles on the commit message, that is time that goes
| from other productive endeavours.
|
| I think, as the original commenter also wrote, this might be
| worth it in much slower paces projects that is run in another
| cadence / over mailing lists.
|
| I particularly think that high paced application development
| do not benefit from git as documentation.
| floating-io wrote:
| I would argue (rightly or wrongly) that there are two
| common truths to such a scenario:
|
| Scenario 1, you're doing a bunch of small changes that work
| towards a larger purpose. They're what I like to call
| "checkpoint commits". They aren't the whole story --- just
| a step along the way to whatever you're trying to
| accomplish.
|
| Scenario 2, you're coding instead of thinking. Making
| "random" changes until you get what you want, but because
| you're continuously delivering, they all go to production.
| Note that "you" here might be the developer, or it might be
| business people demanding things from said developer.
|
| In scenario 1, IMO you should be working on a branch. Then,
| when you're finished, you squash your commits and replace
| the countless mini-messages ("fixed", "Oops", "wtf?") with
| the _actual_ message you want to be there when you merge
| it.
|
| In scenario 2, especially if it's driven by business,
| you're probably SOL. In this instance, however, I tend to
| feel like people are making more work for themselves. If
| they stopped and _thought it through_ for half an hour
| before starting work, it might only take an hour's worth of
| work and one commit, instead of a day and thirty commits.
|
| Of course, there are always shades in between. :)
| jonathanpglick wrote:
| Until it's 7 years later, the original developers are gone,
| the ticketing system has changed twice, and you have no
| clue why something is the way it is.
|
| When you're committing is exactly when you already have the
| context of "why" loaded and even a short explanation should
| be quick to write. The thought cycles argument feels lazy
| unless you're doing a bunch of quick exploratory commits
| and clean up/squash your git history later and add context
| once a solution solidifies.
| tetha wrote:
| > I think, as the original commenter also wrote, this might
| be worth it in much slower paces projects that is run in
| another cadence / over mailing lists.
|
| Very much this.
|
| If I'm modifying some rather obvious and ovreall simple
| thing like an obvious config of a grafana, adding a
| customer to a config and such things... it's hard to really
| bother with a long commit message. Also, with modern tools
| like VSCode with the Gremlin plugin, I don't think I'd have
| spent many words on removing a weird whitespace from a code
| base, to be honest.
|
| On the other hand, if I've spent 4 hours thinking and 2 of
| those hours discussing the change with another DBA changing
| a 2 into an 8 in the config of an SLA-critical postgres
| cluster... spending 10 minutes on a commit message in the
| config management is - with regard to time - a footnote,
| irrelevant and inconsequential.
|
| But it can be worth more than gold down the road if you ask
| "Why 8? Why not 6!"
| sunshowers wrote:
| > On my work I make 1-15 commits a day. If I have to spend
| thought cycles on the commit message, that is time that
| goes from other productive endeavours.
|
| I make roughly that many commits a day as well. If
| something's easy to understand I'll put in a simple commit
| message (e.g. [1]), but I do put in the effort for more
| complicated ones.
|
| [1] https://github.com/nextest-
| rs/nextest/commit/efd194b2e1d8d61...
|
| [2] https://github.com/oxidecomputer/omicron/commit/b07a8f5
| 93325...
| palata wrote:
| > On my work I make 1-15 commits a day. If I have to spend
| thought cycles on the commit message, that is time that
| goes from other productive endeavours.
|
| Do you apply that to everything? Like not answering
| questions from your colleagues, not writing test, not
| refactoring, not optimizing, etc?
|
| I personally don't measure my productivity by the number of
| commits I push. If I did, I could easily make 100 commits a
| day. And there of course it would be better for me to not
| care about the commit description, because it would take
| thought cycles and anyway the commits would make no sense.
| gorkish wrote:
| Making sense of code (or any system that changes over time) vis
| a vis its own history is one of those things where I really
| think AI/ML tools can really shine. Even with relatively low
| quality commit messages, I can look at something that happened
| 15 years ago in a codebase I am familiar with, and there will
| probably be enough information that I can assemble the full
| context, even if finding some of that information is
| challenging or time consuming. git log, git blame, look at the
| other code made in the commits, read the issue descriptions,
| read the code reviews. It just seems like a model could slurp
| that up and do a decent job of giving you a couple of
| paragraphs about why the line of code you are staring at is the
| way it is.
|
| TBH putting such a detailed writeup in the git log doesn't
| really have any return -- for it to ever be useful to you
| again, you have to know the information is there; you then have
| to actively seek it out, with the hope that whatever you did to
| make it 'searchable' is going to work for you again. I can say
| with surety that if I were looking at a bug similar to the one
| linked from this article, I would not look to the git log for
| inpsiring a fix; I'd just fix it. Any extra time I would take
| would be to understand how a UTF8 nbsp ended up where it
| shouldn't have been in the first place -- something that the
| author of this commit seemed to have no interest in doing, but
| which likely has greater relevance than the documentation of
| the fix.
|
| I want to be clear that I support commit messages that say what
| they do though; I'm not advocating for -m 'fixed' shenanigans,
| however at the same time I believe that -m 'fixes #1234' is
| often enough
| keybored wrote:
| I'm surprised that you (in particular) would say this. git-log
| is, to me, fine for displaying the whole message (not just the
| subject). And sure, I often fiddle with copy-pasting SHA1s like
| a caveman, but it's fast enough for some quick history
| spelunking.
|
| Finding the history of a particular code change is even more
| manual for me: maybe doing a chain of `git log -S'line'` where
| `line` copy-pasted in at every step. But doable and not a time-
| sink for my off-hand what's-this thoughts. (But: something more
| convenient that isn't an unreadable Unix pipeline one-liner
| would be very nice.)
|
| My litmus test is simple and doesn't involve hallucinating that
| other people are even reading my messages: am _I_ reading my
| own past commit messages? Yes. I am curious why I did or didn't
| do something on a daily basis(!)
| ManuelKiessling wrote:
| I agree for the use case of scrolling through a git history,
| yes, but when I land at a certain commit, e.g. by hitting the
| blame label in IntelliJ on a line whise reason d'change I'm
| interested in, then I will totally read the whole commit
| message in the hope that it helps me understand the change (in
| addition to looking and trying-to-understand the change
| itself).
| lisper wrote:
| > The main issue is that most of the tooling ... generally only
| shows the first line.
|
| > I don't know exactly what the answer is
|
| Isn't it obvious? Write better tools. There is no reason you
| have to be stuck with the deficiencies of what someone else has
| built. That's the _whole point_ of open-source software.
|
| It's more than a little concerning that a "GitHub cofounder and
| author of several Git books" has to have this pointed out to
| them.
| ParetoOptimal wrote:
| >There is no reason you have to be stuck with the
| deficiencies of what someone else has built.
|
| There is a concerning trend of "we only use vscode" and
| popular preference shifting to "adjust to popular tool"
| rather than "use best tool".
|
| This means sadly things like GitHub start to define git even
| more for your coworkers.
| caskstrength wrote:
| > Even if you're _very good_ at Git, finding the correct
| invocation of "git blame" (is it "-w -C -C -C"? Or just _two_
| dash C's?) to even find the right messages that are relevant to
| the code blocks you care about is not widely known and even if
| you find them, still only show the first line. Then you need to
| "git show" the identified commit SHA to get this long form
| message. There is just no good way to find this information,
| even if it's well written.
|
| The good way to browse git blame a read commit messages is to
| use Magit. It is also great at letting you seamlessly
| rebase/split/merge long patch series.
| zellyn wrote:
| If you follow a pull-request based workflow, and if you
| typically squash down to one commit, then finding these
| messages isn't too bad, since the commit description pre-
| populates into the pull request description. I often track
| changes down not to their commit, but to their pull request.
|
| Granted, that's not exactly `git`, but rather `github`...
| nightfly wrote:
| git log. git blame, grab hash, git log hash. You make it sound
| like some arcane magic...
| kelnos wrote:
| While this may be how most people interact with git, I couldn't
| disagree more when it comes to my personal use.
|
| I use 'git blame' (I've never needed to pass any options to it)
| and 'git show' liberally if I'm trying to understand a change
| that was made, and if the committer took the time to write a
| commit message body, of course I'll see it and read it.
|
| > _... I think why people just don 't care much about good
| commit messages. It's just not easy to get this data back once
| it's written._
|
| I think people don't care much about good commit messages
| because they are unprofessional and sloppy. They just want to
| get the commit in, push the PR/MR, get it reviewed and merged,
| close that Jira ticket, and get credit for those sweet sweet
| story points (ugh). And on top of that, they generally don't
| care to document their changes because they personally don't
| see the value of doing so. Surely they'll remember the change
| if they ever revisit it (no of course not, but many people
| think they will), and they don't really give much thought to
| the possibility that others might need more context.
|
| And besides, all the discussion about the bug or feature or
| whatever was happening in the bug tracker, so providing a link
| to that issue in the commit message is enough, right? (No, it's
| not; I hate it when people do that and think that's all they
| need to do.)
|
| > _The main issue is that most of the tooling (in Git or GitHub
| or whatever) generally only shows the first line._
|
| Then maybe this is GitHub's fault; fix your web UI, then. I
| avoid GUI interfaces to my dev tools as much as possible, and I
| think the git command line is perfectly fine for this. It
| absolutely does not only show the first line, generally. 'git
| log', 'git show', etc. give you the full message by default. In
| general I would say you have to go out of your way (by
| providing more command line options) to hide the message when
| using the command line tools.
|
| > _the Git commit message is a unique vector for code
| documentation that is highly sub-optimal._
|
| Sure, because it's not a vector for code documentation, it's a
| vector for _change_ documentation. And there 's no better place
| to put the description of a change than in the record of the
| change happening.
|
| While I agree that many people write very poor commit messages,
| I don't think the tooling and discoverability is why.
| jeremyw wrote:
| I take Scott's point with a difference perspective.
|
| Though commit messages are ephemeral and hard to utilize in the
| future, they're the stream of consciousness of the project.
|
| They convey very important shifts in direction, discoveries in
| the making, code smells, limits of current architecture, and
| markers of tech debt. We don't know what this beast will be.
| And we figure it out commit by commit. Document it.
| jakub_g wrote:
| In my experience it all depends on what kind of codebase it is
| (product? library/framework? private company? opensource?),
| commit velocity, release cadence & how the codebase is used in
| general.
|
| In low-velocity opensource libraries, good and clean commit
| messages can be really helpful when debugging arcane issues. I
| used to be maintainer of a frontend framework & widget library
| and we tried to have good commit messages as we'd often go back
| when over old commits when fixing bugs.
|
| I agree that using git from command line for blame is not easy,
| this is something I always do from GitHub UI instead.
|
| When GitHub is the repo's choice for PRs, and the codebase is
| product codebase with high velocity, having a pristine git
| history and clean commits and commit messages is not practical;
| however, the expectation should be to at least have good _PR
| descriptions_. When blaming commits in GH UI, it 's easy to go
| to the PR which introduced the commit (it's linked below commit
| title); and PR descriptions can be enforced via templates in
| .github folder.
|
| PR descriptions have an advantage that they can use images,
| videos etc. to better explain what they change. This is
| especially useful for frontend codebases.
|
| I work on a big frontend monorepo. We have tools in place to do
| _visual bisect_ between pull requests (each PR gets its own
| preview env). We very much _do read_ PR descriptions when doing
| bisect to confirm which of the recently merged dozens of PRs
| introduced a regression in production N hours ago.
|
| But in general I agree that commit messages are not good place
| to storage general knowledge (they're good for "what and why is
| changing here"). For documenting gotchas etc. I prefer to have
| code comments in relevant places of code; or README.md in
| subfolders. (Sadly, I notice most programmers just don't
| document anything anywhere at all).
| b33j0r wrote:
| Author of nit, here. I tried to move the landscape towards
| semantic reasoning. It's on github but kind of abandonware.
| Life and incompetency happened ;)
|
| No shilling. I commented here because I still think my
| framework was decently thought out, and mostly that calling
| someone a nit or a git is exactly what linus was thinking. Make
| it easy enough for anyone to use.
|
| Nit is something people could take as a thought experiment.
| twosdai wrote:
| 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.
| 6510 wrote:
| Just do a threaded conversation in a comment at the top of each
| file. Add your name and the date.
| krobelus wrote:
| > The main problem is that Git was built so that the commit
| message is the _email body_, meant to be read by everyone in
| the project.
|
| I find this very hard to believe. Isn't it "everyone who is
| interested in the commit subject/files touched should read the
| body". Why would anyone else read immutable historical
| documentation?
|
| > Even if you're _very good_ at Git, finding the correct
| invocation of "git blame" (is it "-w -C -C -C"? Or just _two_
| dash C's?) to even find the right messages that are relevant to
| the code blocks you care about is not widely known and even if
| you find them, still only show the first line. Then you need to
| "git show" the identified commit SHA to get this long form
| message. There is just no good way to find this information,
| even if it's well written.
|
| This sounds like you are joking. Any good IDE will be able to
| annotate each line with blame info, and show the diff at the
| press of a button. On such diffs, the IDE should allow
| recursive blaming on context/deleted lines. Tools like Tig
| allow exactly that.
|
| GitHub certainly does make it hard to see commit messages, I
| give you that :)
|
| > Hundreds of hours of amazing documentation from a true genius
| that almost nobody will ever appreciate. It's horrifying.
|
| ?? It's not like it was written for fun. This documentation
| attached to a commit exists to reduce the risk of accepting the
| patch from someone who might not be around in future, to fix
| any problems introduced. By disclosing all their relevant
| thoughts, the author shows their good intentions: they enable
| others to build on top of their work. If the author kept their
| thoughts to themselves they would gradually build up exclusive
| ownership of the code, which is often not a good idea. Also a
| commit message serves as proof of work, which can be important
| when there's too many patches. For commercial projects some of
| this is less important.
| tibbar wrote:
| In practice, I think GitHub/GitLab/etc solve this UX problem
| pretty well. Inline git tools let you jump immediately to the
| PR that generated the code change, and the PR description +
| code reviews + snapshot of the commit help to understand what
| the point of the change was. You can search the PRs when you
| want to find some context. (It's unfortunate that PRs are not
| stored in the repository itself. I mean, Git is not a great
| database for a multi-user webpage, so this wouldn't quite
| work... but it would be nice if the archive was durable and
| easy to export/share.)
| sohamssd wrote:
| Your entire argument boils down to the fact that it's hard to
| view git blames. It's not.
|
| As stated by other people, IDEs like VSCode and IntelliJ do an
| extremely good job of showing the blame. And they DO show the
| entire commit, body and everything at once.
| da_chicken wrote:
| > The main issue is that most of the tooling (in Git or GitHub
| or whatever) generally only shows the first line.
|
| This has been an issue with version control tooling for quite a
| long time. I'm fairly certain both CVS and SVN did the same
| thing. But I agree that you're still right.
|
| I'm also very amused by the number of replies to your comment
| along the lines of, "oh, it's actually very easy because I
| always use <third party tool>".
|
| Which is, of course, rather proving the point.
| dragonwriter wrote:
| No, because the point is about common tooling, and the common
| tooling does not, actually, make this difficult.
| palata wrote:
| > The main issue is that most of the tooling (in Git or GitHub
| or whatever) generally only shows the first line.
|
| Maybe I do it wrong, but the most basic interface I use to
| check the git history is `git log`, which shows the whole
| commit message.
|
| GitHub takes me 18 clicks to find the commits, I don't see why
| I would even bother using it.
| ParetoOptimal wrote:
| Many engineers primarily or even exclusively use git via
| githubs interface and have never made a commit with a body.
| cerved wrote:
| Those "engineers" go on _The List_
| mo_42 wrote:
| I have a different opinion about favourite Git commit messages.
|
| I think commits should be small steps that display the thought
| process of the author. Every individual commit should be self-
| explanatory. So the commit message should not describe (again)
| what the changes are but why it's necessary. Sometimes the change
| is not self-explanatory and then I'd put a longer description
| below.
|
| Somehow I came up with this on my own, so I'd be interested if it
| really makes sense or if others have a similar style.
| kelnos wrote:
| I just don't think this is feasible, and I think you're maybe
| over-estimating the diff-reading skills of others. I agree that
| changes should be as small and self-contained as possible, but
| I don't think it's reasonable to expect a later diff-reader to
| be able to understand what the change is just by looking at it.
|
| Certainly a commit message should include the why, but it
| should include -- start with, really -- the what as well.
| gumby wrote:
| That first line of the commit message is most important so that
| `git log` can address chesterton's fence. And IMHO in this case
| the committer whiffed.
|
| The key is not to put _what_ you did in that first line, but
| _why_. Anyone interested in what can just look at the code,
| perhaps via a diff.
|
| So something like "nginx .conf files must be in us-ascii"
|
| Then "changed blahblah.erb to remove nonbreaking space character"
|
| Then the rest of the commit message which is quite good.
|
| Think of it as a news article: write in decreasing levels of
| importance and increasing levels of detail, assuming the reader
| could stop reading at any point.
| nathan_phoenix wrote:
| > Think of it as a news article: write in decreasing levels of
| importance and increasing levels of detail, assuming the reader
| could stop reading at any point.
|
| Great quote and life advice, will definitely steal this!
| Thanks!
| hatsix wrote:
| Nah, first line needs to be a summary of what you changed, so
| that you can find the offending commit in the first place.
|
| A news article doesn't explain WHY in the headline, it explains
| what.
|
| In this case, the OP's first line is spot on... if you're
| reading through git log, you can see that this commit likely
| didn't change anything functional about a test, and you should
| move on.
| tux1968 wrote:
| Hard disagree.
|
| There's little reason to search the text of commit messages
| to find out what changed. There are many git tools to find
| out which commits affected parts of the code you're
| interested in. Whereas, trying to find that in commit
| messages is really inefficient and relies on reading, rather
| than such automated tools.
|
| The purpose of the commit message is to help our fellow
| humans get a higher level understanding than is available
| from quickly scanning the code.
| hermitdev wrote:
| Totally agree with you.
|
| We already know _what_ changed: it 's the diff! We need to
| know _why_ you 're making the _what_.
|
| The message should address _why_ the diff is necessary. Was
| it a bug fix? Ok, what 's the bug you're fixing? What's the
| evidence that you think they diff addresses it? Is it a new
| feature? What's the requirement? I can already tell _what_
| you did by the diff, but I can 't tell from the diff alone
| if it actually matches the requirement!
| joshuamorton wrote:
| This is true of the overall commit message, but we're
| talking about the first line. If I'm browsing git-log
| short or whatever, I _don 't_ have the diff, I have an
| ordered list of commit hashes and one line summaries, and
| I'm trying to decide which diffs I actually want to look
| more closely at.
| myaccountonhn wrote:
| I've never thought about it this way.
|
| I've always used it as a summary, so I can understand what
| has been done when browsing the history. It allows me to
| find changes that I want to cherry-pick or revert. OTOH I
| can see benefit of describing why a change was done as the
| summary, as then git blame on the line is a lot more
| effective.
| joshuamorton wrote:
| But a commit message in an arbitrary project is not where you
| give someone a lesson about nginx rules.
|
| "nginx .conf files must be in us-ascii" is maybe a good bug or
| pull request title, but it may correspond to multiple commits
| that do different things, but it doesn't tell me what's
| happening. Is this converting a file to us-ascii, is this
| writing a tool to convert files to ASCII, is this updating
| documentation, is it creating a test, some combination? Leading
| with what, not why addresses that confusion.
| palata wrote:
| > The key is not to put what you did in that first line, but
| why.
|
| Can't we just say that the key is to put something that makes
| sense for the first line, given that sometimes only the first
| line is printed?
|
| I don't really care if it says "The files must be in us-ascii"
| or "Changed the files to us-ascii"... both of them clearly tell
| me that the files were changed to us-ascii.
| AeroNotix wrote:
| Essentially zero people read complex commit messages.
|
| Do with this information what you will.
|
| 9/10 the code already is documentation enough for what the code
| currently does, if you need to go back through history then look
| at the commits. The messages are generally noise.
|
| I've literally never cared _why_ someone made a change, I can see
| the change, I can see the effect of the old and new code. Rarely,
| if ever, has the thought process ever changed how I will interact
| with the code in question.
|
| If I am at the level of debugging or history spelunking that the
| _commit message_ is the thing that saves me - I've already lost
| and there are other glaring organizational or design issues that
| are the actual problem.
| advisedwang wrote:
| > Essentially zero people read complex commit messages
|
| I don't think that's true. I worked in support doing break/fix
| and outage response work at a large organization. That means
| constantly dipping into codebases I'm utterly unfamiliar with.
| Often there is complexity, un-obvious elements, previous
| incorrect attempts at a bugfix and so on, where understanding
| what the author intended can save literal hours of examination,
| experimentation etc.
|
| > If I am at the level of debugging or history spelunking that
| the _commit message_ is the thing that saves me - I've already
| lost and there are other glaring organizational or design
| issues that are the actual problem.
|
| This is kind of understanding what I mean, but there was no
| organizational or design failing here. This is just the nature
| of some work, I believe.
| AeroNotix wrote:
| > [..] where understanding what the author intended can save
| literal hours of examination, experimentation etc.
|
| The problem with that it that you are relying on an
| inherently unreliable source of information - a human to
| enter details which may or may not lead you to the correct
| path.
|
| The code doesn't "lie". Just read it and the current issue
| and work from there.
| gray_-_wolf wrote:
| The code might not lie, but is also does not tell you _why_
| the DNS record in your IaC was changed from 1.2.3.4 to
| 4.3.2.1...
|
| Well written commit messages are useful. Some people use
| issue tracking system instead, but commit message should
| have the information in more concentrated form instead of
| spread over 50+ messages of discussion.
| jotaen wrote:
| The code may tell you _what_ it does, but that doesn't
| necessarily tell you _why_ it's there.
|
| Especially for non-obvious pieces of code I have to deal
| with, I certainly prefer to understand the original
| reasoning and context within 5 minutes by looking at the
| original commit / PR, than having to spend multiple hours
| rediscovering that one quirky edge-case scenario that
| someone else already dealt with 3 years ago.
| kelnos wrote:
| > _The code doesn 't "lie". Just read it_
|
| No thanks. Some diffs aren't obvious. I'm not a mind
| reader. Having extra context is useful.
| advisedwang wrote:
| Code doesn't lie, but it isn't always obvious either. A
| diff that fixes a subtle corner case is very difficult to
| understand without explanation. A function to fix dirty
| external data cannot be understood without reference to
| what the author is fixing. It may not be clear why a
| certain performance trade-off is preferable. A mistake may
| be hard to detect if you don't know what was intended.
| kelnos wrote:
| Even if it's true that essentially zero people read complex
| commit messages, that one person who needs to read it, 2 years
| later, will really appreciate its existence.
|
| To me a commit message isn't there so someone can sit around
| and read commit messages to tell themselves a story. It's there
| in the -- hopefully unlikely -- possibility that there's a
| problem with the change, and someone needs to come back to it
| later, with no context, and understand why it was made so they
| can figure out what needs to be done.
|
| I've absolutely used commit messages when debugging, and I
| don't think there's anything wrong with that.
| eduction wrote:
| It's true that giving a little potted history like this is "good"
| (other than he should have made a nice informative first line for
| summaries)
|
| BUT it's not super useful to say this is good, the hard part is
| knowing WHEN to put this much effort in and when you can skip it.
|
| I have many instances where I could do a longer story like this
| but it would be exhausting to do it every time. I try to do it
| when the commit might look unclear in intent or effect to an
| outsider, when the change is being made for an important reason,
| /and/ where this a potentially negative consequence (like naively
| reverting or writing bad code) if the change is not explained.
|
| I think this is a decent example of that but not great, because
| no one is intentionally going to go in and start introducing
| nonbreaking spaces.
| cesarb wrote:
| > BUT it's not super useful to say this is good, the hard part
| is knowing WHEN to put this much effort in and when you can
| skip it.
|
| I learned git in the context of Linux kernel development (its
| original use case). In that context, the commit message is
| where you explain, to whoever is reading, what your change does
| and why it should be accepted. The more subtle the change is,
| the longer and more detailed the explanation must be to
| convince a reviewer.
|
| So basically, the rule of thumb would be: pretend you're going
| to email your commit to another developer, who has the power to
| accept or reject your change, and who is not going to consider
| anything outside that email in their decision. The more subtle
| your change is, the more detailed and convincing its
| explanation has to be.
| krmbzds wrote:
| I would just go with "Remove non-breaking space characters"
| instead of writing a Russian novel.
|
| Also, if you're on macOS just use a Karabiner rule [0] that
| converts all non-breaking space characters to regular space
| characters to prevent yourself from accidentally typing it out.
|
| [0] https://ke-complex-modifications.pqrs.org/#nonbreaking_space
| hoherd wrote:
| There are also pre-commit hooks to remove the character, even
| one listed on the pre-commit site. This type of hook has saved
| me on many occasions, and would have saved my coworkers if they
| used pre-commit.
|
| https://pre-commit.com/hooks.html
| thrdbndndn wrote:
| I'm surprised the author (of the git commit) put that much effort
| into the message, but did not mention what exactly that character
| is (its Unicode code point).
| eviks wrote:
| The uberdetailed exploration is worthy of a blog post, those are
| for stories! but a commit is way too obscure a spot to put it in,
| so it's just a waste of effort on the writer side, but also a
| waste of attention of the readers, a short message describing why
| a change in space resolved which bug where would be more
| efficient
| ryandrake wrote:
| Git commit message aside, the described debug session raises a
| lot of questions about the crappy tooling developers rely on.
|
| "ArgumentError: Invalid byte sequence in US-ASCII" is a terrible,
| hard-to-action error message. What file? What line? What byte
| sequence? This "let's give the user another problem to solve"
| style of error messages is pervasive in our tools.
|
| Also, why does the tool even require US-ASCII as input in the
| first place? Are we still living in 1995?
|
| Also, if only ASCII characters are allowed, why does the code
| editing tooling allow non-breaking spaces in source code? Is
| there a good reason for having such a character in this file?
| This problem could have been avoided if the editor could have
| been smarter or highlighted the "bad" character better.
|
| This developer lost an hour of his life because of a cascading
| chain of defective tools.
| MeteorMarc wrote:
| When a developer admits that a single wrong character cost them
| one hour, it probably took 3 hours.
| gavinhoward wrote:
| I'm about to release 1500+ commits. I hope people will be able to
| praise some of my commit messages like this one.
| mrinterweb wrote:
| This is the reason I dislike automatic squashing branches with
| rebase. Squashing discourages thoughtful and meaningful commit
| messages. What is the point of making a meaningful commit message
| for some specific change when it is just going to all be smashed
| together as a single commit on merge. I feel like rebasing is
| something that should be intentional to clean things up by the
| dev, but not as a default pattern on merge.
| gfiorav wrote:
| My rule for any developer doc is: don't tell me what, tell me WHY
| fl0ki wrote:
| A complementary virtue is that the commit is tightly scoped to
| exactly one change. I still see most engineers commit whatever
| they had in their working directory as a sort of blanket Save
| Point, without any thought to how those changes can be captured
| as individual commits that can be commented and reviewed on their
| own merits.
|
| This will typically also involve completely unnecessary changes,
| because when you're merging unrelated changes anyway, the
| unnecessary ones are swept up in the noise. At best they
| complicate rebases for other contributors, but too often they
| also cause outright regressions.
|
| It goes without saying that the commit messages are a write-off
| at this point, because even if they felt motivated to take the
| time to comment it clearly, the change is so messy and nebulous
| that it becomes hard to comment on. If their code gets reviewed
| it's more likely the reviewer gives up and stamps it so they no
| longer have to look at it.
|
| Most people still don't seem to know that `git add -p`, `git
| reset HEAD`, `git stash`, `git rebase --interactive`, etc. are
| even available. They never learn what git is capable of, so they
| act like version control is a bureaucratic obligation rather than
| the peerless superpower that it can be. The problems they cause
| don't end at their terminal though, because now they've made a
| mess of the repository for every other contributor as well.
| declan_roberts wrote:
| Is it a trend now to write the blog post as the commit message?
|
| I must be getting old because I hate this.
| Forge36 wrote:
| Previous discussion https://news.ycombinator.com/item?id=22519632
| dang wrote:
| Thanks! Macroexpanded:
|
| _My favourite Git commit (2019)_ -
| https://news.ycombinator.com/item?id=22519632 - March 2020 (67
| comments)
|
| _My Favourite Git Commit_ -
| https://news.ycombinator.com/item?id=21289827 - Oct 2019 (370
| comments)
| smashah wrote:
| Every country should have a GDS. They do great work.
| macspoofing wrote:
| It's not a great git commit.
|
| 1) For all that text, the first line "Convert template to US-
| ASCII to fix error" - could be better. Maybe a couple of extra
| words to state what whitespace character caused the error, and
| what the error was. That comment plus the diff is all the context
| you need.
|
| 2) Honestly, everything else is kind of pointless. It doesn't
| hurt, but there's not a lot of value here. The author documented
| their journey in tracking this bug .. who cares?
| tehnub wrote:
| I try to write useful commit messages. Sometimes they're as
| expansive as this example, but not always. On GitHub, at least
| the way my team uses it, the PR is the more visible unit of code
| change. If you have a single-commit PR, GitHub will automatically
| make your commit message the PR description, which is nice. It
| does not do that if you have more than one commit, in which case
| I write a general overview of the changes and write "See
| individual commit messages for more detail" in bold.
| vonwoodson wrote:
| My favorite git commit is "Bug fixes"
| darioush wrote:
| In my opinion one of the most important features of a commit
| message is that it fits in a single line so it can be read in git
| log.
| hartator wrote:
| "Fix miss-encoded white space" is clearer to me.
|
| No need for a very lengthy explanation.
| 2devnull wrote:
| 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.
| daitangio wrote:
| 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.
| pawelmi wrote:
| I would prefer to channel that energy that went into writing this
| lengthy description into actually fixing the toolchain to at
| least fail with more actionable error message.
| jiveturkey wrote:
| love those guys at the UK digital service!
| RustyRussell wrote:
| I was told by a recent contributor that my approach (i.e.
| requirement) to git messages is "unique". Apparently my Linux
| kernel background is showing, but all my commit messages look
| like the one shown here!
|
| If about existing code, the comment belongs with the code. If
| it's a process thing (e.g. code that is removed or didn't work),
| it belongs in the commit.
|
| Most importantly, while commit messages can reference issues for
| convenience, they MUST reproduce the critical details: GitHub is
| transient, git messages are not!
___________________________________________________________________
(page generated 2024-02-01 23:00 UTC)