7 ms·

After being in the field for almost a decade now and guilty of so many poor commit messages, I came to the firm realization that a very important trait of a goo

• amelius 7y ago
  Ok, but how much time have you "wasted" wondering what a piece of code was doing versus how much time would you have wasted writing good commit messages?
  • deanmoriarty 7y ago
    It has been an obvious net time gain for my projects. I do a lot of system programming, and often there are very complex reasons why a particular function is called in a non-obvious way, especially after tricky bugfixes. Having a somewhat detailed written record associated with the commit, that won't rot like an inline code comment would, has been very useful in my experience. And all my thoughts become instantly available to all the future code readers, who will most likely not be me.
    • ses1984 7y ago
      >that won't rot like an inline code comment would It's a balance between rot and visibility, right? Unless you code with commit messages always visible, you have to go out of your way to look at them. If the interesting line changes even a little bit, you could hide the commit message explaining everything with one that explains a small change. If I could only have one, I would rather have comments visible in the code, and control they rot through change review, but of course finding a balance between both is the best.
      • saagarjha 7y ago
        > Unless you code with commit messages always visible I do this when tracking down bugs or trying to figure out the design of a particular component.
  • pjc50 7y ago
    I can see what the code is doing. I can't necessarily see why it's doing that and whether it's a bug or a feature. Good messages make ""blame"" extremely useful. It was a constant source of irritation at a previous job where the repository had been imported from a different version control system without history. So half the time "svn blame" would just tell you it was in commit #1 ten years ago, which wasn't nearly enough.
    • nogabebop23 7y ago
      >> I can see what the code is doing. I don't think the reader should have to look at the code to get the summary of what the code does and how it does it. I agree that the "why" should be the focus.
  • nogabebop23 7y ago
    >> how much time would you have wasted writing good commit messages? or time wasted writing unit tests, or pull requests, or code reviews? (1) It's about effective communication. Why do developers appear to care so much about the way we write our code but not the artifacts that form it's ecosystem (and have a much wider audience)? (2) If you're going to write a commit message, why not take the incrementally very tiny extra bit of time to do it right? If you don't really care about the quality of your commit messages I'd suggest stop requiring them and allow blank commits. IMO this is preferable over the false impression that a garabage commit history provides any value.
  • dtech 7y ago
    It's a balance, but I've definitely seen that a good commit title can massively help newcomers, yourself when you can't remember why something is the way it is and can be a boon when debugging. A nice balance I've found is to not care while developing, but then squash all commits into a single one when merging a pull request and give that a good message.
    • katbyte 7y ago
      This is what I do, means I don’t have to worry about describing a “fix linting errors” commit. Just on squash merge ensure the commit message captures what’s required (and on gh the pr is automatically included and I typically put any linked issues in the additional info area)
  • 0xEFF 7y ago
    It's not wasted, sloppy commit messages are correlated with sloppy code. Thinking through describing the change in prose has an immediate positive impact on code quality.
  • nemetroid 7y ago
    For me it's definitely in the first category, and I take my time writing good commit messages. It also serves as a good filter for commit content. If you can't write a good, comprehensive commit message for it, it probably shouldn't be its own commit.
• genzeddev 7y ago
  I think part of the issue is that for someone who's been writing English for 15 years, knocking out 2 paragraphs of cogent explanatory prose is as easy as ABC. But for someone who is relatively new to the English language, this can be the source of much anguish and frustration. Doubly so for something like a commit message that is immutable by design. The idea of a typo, a bad idiom, or even worse, unintentionally offensive phrasing, being surfaced for all to see 10 years from now can be a frightening prospect. I think this whole discussion goes to show the nature of institutionalized privilege, and how seemingly innocent requirements can have a disparate impact on marginalized groups.
  • deanmoriarty 7y ago
    I can somewhat relate to that, since I am not a native English speaker and it took a while for me to become proficient with the language, but I can say that in the teams I worked in it was mostly a matter of sloppy culture.
  • ben_jones 7y ago
    > But for someone who is relatively new to the English language We decided to structure our front-end application using Atomic Design which classifies UI Components in a hierarchy of Atoms, Molecules, Organisms, Ecosystems, and Pages. Pretty universally the definitions of these terms did not translate to many of our remote developers in other countries not only because of the language but likely they didn't have the same Biology education either. This and other similar revelations have led me to always put myself in the shoes of anyone reading my code, comments, commit messages, and force myself to use simpler language whenever possible.
  • nguoi 7y ago
    Fundamentally, I think you are correct, however my English-second-language friends/colleagues tend to write better English when it's in a structured fashion - like a commit message or in documentation - than they do colloquially. That is how they learned it, after all, while native speakers learn it from osmosis. It's rare to see the ESL speakers use the wrong there/their/they're like native speakers do.
  • 7y ago
• axaxs 7y ago
  What in your opinion is the benefit/difference of this, versus commenting nonobvious code? I tend to prefer the latter. Each time I work on someone else's code, I'm elated if they write longform comments about what they're doing or why. I think tracking down commit messages would be more cumbersome.
  • deanmoriarty 7y ago
    I tend to put comments around VERY tricky pieces of code, but the rest belongs to the commit log. I feel code comments tend to rot because they are not as immutably bound to the code they describe as a commit message is, and for the most part my commit messages are too verbose to end up in code comments, it would create too much clutter. I have a good integration with my editor that shows inline blame annotations for the current line (and full message is a keystroke away).
  • pm215 7y ago
    Good comments are important too. But comments describe the code as it is at this point in time ("why is the code doing X?"); commit messages describe the change ("why are we making the code do X rather than Y?"). Sometimes the same information should go in both places; but the focus and emphasis when you're writing the description up varies. A good commit message is also really useful for code reviewers: it sets the stage and contextualises all the code they're about to read.
    • axaxs 7y ago
      Both good points to consider - thank you.
    • mumblemumble 7y ago
      To add to that, probably at length: Some information is a pre-requisite for understanding a specific block of code. This information is a great fit for comments, because everyone who's looking at the code will need to know it, and having it in a comment ensures that it's discoverable. Other information is a pre-requisite for understanding the engineering or business decisions that motivated a design decision, but isn't necessary for understanding how the code works or how to interact with it. That makes it less appropriate for comments, because the comment would just be clutter (light pleasure reading at best) under the most typical use case. People who are engaging in those use cases should know how to use git blame to find what they need. For still others, the unit to which the information applies is not a block of code; it's a set of changes. In those cases, comments are a terrible choice for conveying that information. Maybe a commit message is better. If it's not, you probably need to be looking to a project wiki or some separate documentation files, so that the information can be written and maintained in one place. You can still use comments, but they should merely cross-reference the centralized documentation. Today's copy/paste is tomorrow's outdated and misleading misinformation.
• getpolarized 7y ago
  I've been a Software Engineer for 15 years now... 10 years in the industry as a systems engineer before that. I sort of agree but what I try to do is put more comments and documentation in the source code directly. The problem is that commit messages are usually hidden only when there's a problem. Comments are there for the life of the code. The problem with comments though is that they could go stale and something could be refactored. I try to put them directly on methods/functions more and not on specific lines of code. If I have to document a line of code it probably is a sign that it should be a function/method itself as it's a bit too funky to just stand alone. Commit messages are GREAT for tracking down when something is broken though. Would be nice to have your IDE take your code comments and make commit messages for new methods and the documentation for that method/class.
  • iudqnolq 7y ago
    Jetbrains can be set to show you the last commit message that modified a chunk of code. I assume there's a way to do this in vim/emacs for the sufficiently motivated as well.
    • morelisp 7y ago
      This is basic functionality via `git annotate` (which goes back, at least, to `cvs annotate`). It is also built into Emacs as `vc-annotate` (default `C-x v g`), though `magit-blame-addition` is a better option for projects using git.
      • iudqnolq 7y ago
        Awesome. Was missing that in emacs. Magit continues to surprise and delight me.
  • lhorie 7y ago
    It doesn't need to be an either/or affair. Often times, I'll add a comment to a particularly tricky piece of code, but then also comment in the commit message (and then again in the PR in Github for the code reviewer) Often times, even a copy-paste is better than nothing. Better to over-communicate
• weberc2 7y ago
  We tag each commit with the (JIRA) ticket ID. The ticket has the broader business context, and the commit message is generally shorter. There's still some gap between the one-line commit message and the ticket ID, but it hasn't really caused problems in our org to my knowledge.
• alunchbox 7y ago
  Assuming you're doing Git based flow branching off of Develop or Master to do changes. Before merging your changes back in do you rebase and cleanup the messages or squash? I feel like every company I work for just does merges everywhere and history is 99% unreadable at this point without filtering out certain things on the log and even then. Any tips on how you're able to keep things clean for the entire team ? What's your usual workflow? I've read through Martin Flower and a few other blogs on this topic yet have never understood how to avoid "add x", "fix foo".
  • julik 7y ago
    We disabled merge commits on all of our repositories on Github, and rebase is used seldom - meaning that when you do merge you are presented with an edit box for the squashed commit message. This incentivises one to actually write good prose inside that box. We are not perfect but getting there.
    • Rondom 7y ago
      That's interesting. Working in an organisation that switched from Gerrit to Github, I saw a decline in commit message quality. Some people will just leave whatever is filled into the textbox by GitHub. In addition, there is no way for others to review the commit message this way.
• giancarlostoro 7y ago
  > These days, every single commit I push has an entire paragraph or two clearly describing the changes, and the motivation behind them, even if it's a one-line diff. I used to do this, but prefer the list form. I like to note what has been added or removed, if you're searching through the commit history it's all useful.
• stinos 7y ago
  every single commit I push has an entire paragraph or two clearly describing the changes, and the motivation behind them Similar here, but: looking back at a couple of years ago I obviously went through a phase where I was just writing complete paragraphs for the sake of making sure the commit looks meaty. So now I treat messages the same as code: code not written is good. If a one-iner is enough to explain why something was done, and the changes in the code speak for themselves, than that's it. even if it's a one-line diff. By now you probably figured the size of the diff doesn't seem to have much of a relationship with the amount of commit message needed :)
• hinkley 7y ago
  We have a precommit hook that insists on a ticket being in the commit message, which helps. Except some idiot migrated our bug database to a new server and re-numbered the tickets in the process, so only the last two years are intelligible.
• hinkley 7y ago
  I also think it's more important to think of a commit as a performance piece. The words matter but the shape is more durable. You can comment the commit all you want, but if it contains three separate and unrelated activities then the commit will still be 'muddy', whereas 3 commits with bad comments but one activity per is far more legible. Remember, nobody is reading your commit messages, your tests, or (probably) your documentation unless something is already wrong. Then they're already stressed out and trying to grovel through your information. They're already biased toward being grumpy. Don't add onto that. I'm only reading your commits trying to figure out if a bug is a feature poorly realized or not, so I don't break something else.