17 ms·

> commit messages to me are almost as important as the code change itself This is high on my list of code craftsmanship points. It's very difficult to explain

> commit messages to me are almost as important as the code change itself This is high on my list of code craftsmanship points. It's very difficult to explain to young programmers who have never worked on an old code base how valuable this is when done well. In fact, often you hear complaints about how a code base "is crap", but more often than not I'd wager this is just a result of the context at the time not being known or appreciated. Frankly, all code we write is heavily governed by context we take for granted at the time, but is in precious short supply 1, 5, 10 years later. If you come back with a different use case later, the original code may very well be unsuited for that purpose. We can argue all day about good judgement and YAGNI, but at the end of the day no one can see all ends, therefore the best we can do is document clearly why we did what we did. Taking the time to rebase, cleanup, and explain your changes in detail will pay huge dividends for any long-lived project. I've literally had successors write me a thank you note for a commit message from over a decade ago because I take this so seriously.

technics256 6y ago
Where can one learn the art of excellent commit messages and when to rebase, etc?
- dasil003 6y ago
  This is a good start: https://chris.beams.io/posts/git-commit/ https://chris.beams.io/posts/git-commit/
  - teddyh 6y ago
    See also: • https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst?id=HEAD https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/lin... • https://git.wiki.kernel.org/index.php/CommitMessageConventions https://git.wiki.kernel.org/index.php/CommitMessageConventio...
    - u801e 6y ago
      This is another good reference: http://who-t.blogspot.com/2009/12/on-commit-messages.html http://who-t.blogspot.com/2009/12/on-commit-messages.html
- deleted 6y ago
  [deleted]
- g-b-r 6y ago
  There's no "excellent", it's all opinions. Just look at the "imperative" that almost everyone recommends, try for enough times to cherry-pick commits that claim to do something and you'll realize how misleading they are
nullc 6y ago
> about how a code base "is crap" Translation: "Not written in the particular arbitrary style that I'm used to", of course if it were written in that persons preferred style another arbitrarily selected novice would call the result crap. I've found this to be almost universally true especially when the claim is given forcefully but not immediately backed up with a litany of actual user-impacting serious problems. This is not to say that code can't be crap, but generally people with the wisdom needed to make that determination know better than to waste their time yelling about it and know enough to suggest how to make it better instead. They recognize that good code can be written in a multitude of styles and that there is very little objective evidence for most style choices vs most others. Or, at least, they know enough to limit their forceful remarks to the most objective considerations-- such as code which is actually a source of frequent problems. > Taking the time to rebase, cleanup, and explain your changes in detail will pay huge dividends for any long-lived project. I've literally had successors write me a thank you note for a commit message from over a decade ago because I take this so seriously. Likewise, though more frequently I've been frustrated to see people make grave errors "fixing" correct code that they would have understood if they bothered to look at the message on the commit which introduced the "error" (or read the adjacent comment). The culture of writing good, informative commit messages and comments needs to go hand in hand with a culture of reading them. Neither works in isolation.
- zabzonk 6y ago
  > Not written in the particular arbitrary style that I'm used to Like "arbitrary styles" such as "a function shall not be 500 lines long".
  - trade_unionist 6y ago
    Arbitrary like don't use reflection when a dll will do.
  - Retric 6y ago
    An individual function can quite reasonably be 500 lines long. A giant case statement handling routing is one example. More controversially, if I am gong to need to do a lot of ugly compatibility hacks then I prefer to consolidate them and thus keep most functions clean.
justapassenger 6y ago
This so, so much. Too many people think that commit message is to explain HOW you did something. Unless you did something extremely clever (and in any commercial project, 99% of clever solutions are wrong - simple is the king), it should need more than few words. WHY you did it this way is the most important part. Given known and understood set of constrains, a lot of engineers will come up with similar solution, or at least understand it. And you can’t work effectively on something you don’t understand. Not having this context is reason for so many rewrites. Developer thinks a solution is supper crappy, goes to rewrite it, with grand vision. Only to learn along the way about all the edge cases and reasons for hacks.
- tmh88j 6y ago
  >Too many people think that commit message is to explain HOW you did something. >WHY you did it this way is the most important part. What was done is better suited for the commit message than how and why it was done, in my opinion. The latter two are better explained by comments in the code. I agree that why something was done is important for future reference, but when I'm tracking down code changes I'm looking for hints of the change itself. Understanding why comes next once you have the commented code in front of you to reference.
  - rootusrootus 6y ago
    > The latter two are better explained by comments in the code Totally agree. Commit metadata is nice to have, but ultimately I think good code mostly explains "how" by the code itself, and "why" should be comments. Especially for local context, where the why has to do with some other bit of code. Individual commit messages are also secondary to the pull request merge commit, which should have a better explanation of the goal, or tie it to a task, etc.
  - nemetroid 6y ago
    Requirements change over time, and so do the "why"s. So unless the code base is your primary documentation for requirements, "why" comments in the code can be dangerous: while outdated "what" comments can be determined as such by reading the code, there is no way (from the code itself) to determine whether a "why" comment is still accurate. A "why" comment in a commit message, on the other hand, only tells you what the "why" was at that time, something that cannot become outdated.
musingsole 6y ago
Yeah, but 99% of projects aren't anywhere close to long lived. Most products fail to launch. Most products that launch shutter within a few years. Having a code base survive long enough in close enough to its original state for a commit message to be meaningful a year later is unlikely outside of a few cases. Also, this is all predicated on the business case for the software being well understood that it could be written out beforehand by a entry level engineer. Which is not a situation I've seen outside of a processor design house. Otherwise, your thinking for this or that choice will be built on shifting sand anyway.
- yxhuvud 6y ago
  On the other hand, most people don't work at those short-lived projects. The vast majority of people work for profitable companies that have plenty of long lived code.
- dredmorbius 6y ago
  Short-term coding practices produce short-lived code. Predetermining code longevity is challenging.
- u801e 6y ago
  > Yeah, but 99% of projects aren't anywhere close to long lived. Most products fail to launch. Most products that launch shutter within a few years. Having a code base survive long enough in close enough to its original state for a commit message to be meaningful a year later is unlikely outside of a few cases. A lot of companies run code in production that was written years if not decades ago. Being able to look at the commit history and blame output helps in terms of getting some context about what was done and why it was done they way it was when the original authors have long since left the company. In my company, we still have some code written back in 2005 still running in production.
deleted 6y ago
[deleted]
yxhuvud 6y ago
Another thing those juniors are seldom good at, is knowing how to refactor an existing old code base. Which is not surprising, as everything they worked on during education is new code. Knowing how to change a code base from one abstraction to another is a skill that often take many years and lots of mistakes to learn.
- sushshshsh 6y ago
  Yet another boomer generalization designed to sow biases against hiring younger people. At what age am I allowed to become a senior, oh wise one?
  - abraae 6y ago
    "Junior" is about experience, not age. You can be a junior developer at age 30, or a sage by that same age.
  - bombela 6y ago
    We really gain skill for this over time. As I gain experience, I find that I understand in more details existing codebases. This increased my chance of a successful refactoring. Especially when replacing a core abstraction without a full rewrite.
  - mech422 6y ago
    Usually senior is 5+ years experience... At what age did you start working, oh snarky one ?
  - eggsmediumrare 6y ago
    The tech industry has a lot of problems, but bias against hiring younger people is not one of them.
  - yxhuvud 6y ago
    Which part of my answer gave the idea that this is about age? FWIW, academia have never been good at teaching these skills, so the answer to your question is "You'll stop being junior with regards to refactoring complex code bases whenever you have enough experience of refactoring in big old code bases". Mentors pushing you in the right direction can also help. But this is very much a skill acquired by actually doing.
BurningFrog 6y ago
The maybe most common problem with programmer comments or commit message is what I call "Assumed Context". When you spend a few days deep in a problem, it's very easy to explain the finer details of it while forgetting the big picture of what does this module even do, what real world problem were we fixing, etc, because that has become completely self evident to you. It's a bit like giving a street address without saying what city it's in. I have trained myself to look at both code and comments in a "what if I was a new hire 6 months from now" mode, and it's an indispensable tool for me.
LeonidBugaev 6y ago
Head of Engineering with 15 years of experience here. If found that when we starting using Github flow, with pull-requests and etc, commit messages stopped really matter, in favour of PR descriptions. Plus when you use "squash" strategy, and use PR description as commit message, history looks great. When you look at commit history through Github tooling, all PR ids turned into links, and it is very easy watch for the history. Additionally you have a good integration with Github features, like discussions (which sometimes as important as description itself). Yes it is a vendor lock-in, but lets be frank, Github most likely will survive your project.
- gregmac 6y ago
  The commit message with a good PR description is okay, but for any sizable code change still doesn't provide full context for an individual piece of code (git blame). Either the PR description is massive -- in which case it's hard to read and tell what applies where -- or it glosses over the detail that's necessary. The thing is this isn't obvious why it's useful until you don't have it. I don't do it often, but the things that make me go back looking through git blame and history are trying to identify where hardcoded constants came from, or when (time or version) a particular bug was first introduced and why. This is only necessary when there aren't decent comments in the code already, and in my experience, the types of developers that don't put in these comments are also the ones that don't make highly detailed PR descriptions. Good commit messages is also a hurdle, but an easier one to get over than highly-detailed PR descriptions. On top of that you get all the other significant downsides of a squash merge strategy (eg: not being able to tell the difference between a local branch being merged or not pushed; confusing merge conflicts if you ever merge branch->branch before merging one to master). As an aside, IMHO, "clean history" is not at all a useful feature. Only developers are looking at git log to begin with, and they are quite capable of using `git log --merges` (or equivalent GUI operation). I guess the most useful thing is to make a CHANGES file (release notes) -- but honestly, the wording is different anyway (eg, "Fixed several minor UI issues" is adequate for release notes, but that might be across several PRs that contain more detail like "Fixed button alignment in modal dialogs", "Upgraded bootstrap to version x.y.z" etc). Go back and look at your PR descriptions from a year ago and see if you can make sense of them -- I bet the context of many will be lost.
secondcoming 6y ago
Well, Linux's commit messages kind of have to be descriptive since Linux is an Open Source project that doesn't have (that I can see anyway) an issue tracker or other management tool. When you do have those, then it's the ticket that gives the why's and how's. The commit messages do not have to be essays. And, at least with JIRA, if you name your branch such that it starts with the ticket id, it automatically picks up any pushed commits for that ticket. It's very useful.
- u801e 6y ago
  > And, at least with JIRA, if you name your branch such that it starts with the ticket id, it automatically picks up any pushed commits for that ticket. It's very useful. I've been working at my current place of employment long enough to see them transition between several different issue trackers. The links to old issue tracker tickets no longer resolve, so it's definitely better to include a description of the issue directly in the commit message in addition to the link to the issue tracker.
mrisoli 6y ago
I write detailed commit messages for every single commit I make(even though commits would be squashed on merges), I write detailed PR descriptions that included before/after screenshots in multiple resolutions whenever relevant. Never once did I have any indication that someone took their time to read descriptions or commit messages. In my previous job, I received some feedback from my manager that some people complained about code quality of my work, I was dumbfounded, I have no problem with being criticised, but I at least wanted to be able to learn from it and adapt. I went back through every single PR I did at the company and found little to no comments and it made me feel personally attacked with very little evidence. I then went on my peers PRs and see what I could learn from them, most PRs included highly non-descriptive commit messages and descriptions often only included a link to a JIRA ticket which most of the time was only visible to their direct team members and not me. From that I took the position of being more demanding on not just code quality during reviews but also descriptions, I didn't manage to influence a single developer to improve documenting efforts. That was a major reason why I eventually left the company. I continue to be a believer in taking your time to write good commit messages, I have yet to collect dividends from it however.
- systemvoltage 6y ago
  Yep, no one ever reads them and the cost to benefit ratio is extremely low. Writing good comments is far more important. Don't explain what the code does - that's what the code is for, explain the why and the background information in the code. Additional, explain what the code does at the function level or at the module level - at a much higher abstraction level basically than the line of the code. No one ever looks at the commit messages when trying to figure out what the code does as it convolves history and state of the repository, having to contextually wrap your head around when and how this commit was added. Inline documentation? Perfect.
  - 0xEFF 6y ago
    I look at commit messages quite often working on a 10+ year old code base. Bisect leads to the commit, the commit message explains why the change was made. I take the explanation from 10+ years ago and determine if the reason still applies today. Or, I bisect and there's a low quality commit from 10 years ago from a person long since departed that simply says "fixup" and I'm dead in the water.
ndesaulniers 6y ago
I feel like all of my kernel commits are 50:1 ratio of commit message explaining the bug vs lines of code changed. Each one feels like it's own blog post. One of these days I plan to do a talk on kernel war stories. So many WTF bugs over the years.
mister_hn 6y ago
I've worked with 20yrs+ senior Devs whose commit message is always something like 1 or 2 words sentence (think of "cleanup", "feature X done") and some of there work manually with diff-tools between their local copy of code and the for repository they check out on a different folder. If they're not satisfied with the incoming changes, they just overwrite them and push the overwrite back to repository. This has happened with SVN and also is happening with Git. Unfortunately you can't argue with those ones since are in lead position and there's no one with technical skills above them in the C-level who can say anything (we don't have a CTO or a CIO, just CFO and CEO who can't even use their own iPad)
- mamon 6y ago
  In theory, this could still work if one of those two words put in by lazy developers was a JIRA ticket number where all the details are described in length. Atlassian stack (JIRA, Bitbucket, etc.) even allows you to make those clickable links.
  - mister_hn 6y ago
    Sure, but when your Jira tickets are also poorly described, you have zero ways to track what has been done
- cutemonster 6y ago
  > they just overwrite them and push the overwrite back to repository. I'm not sure I understand what they're doing -- they overwrite some of the changes in their local working tree, and push to the repo, without explaining what they did/what they changed or why?
  - mister_hn 6y ago
    Exactly. They keep a folder which isn't git-sync'ed (they fear the overwrites), then git pull on another folder and with graphic diff tools (e.g. Meld), they compare the changes. If they don't like the changes, they simply recopy the files from the non-sync'ed folder to the git folder and push it (a cherry pick would be too hard for them)
aaomidi 6y ago
Until you use squash and merge. Suddenly commit messages become far less helpful.
- nemetroid 6y ago
  Yep, a good argument against squash and merge.
  - aaomidi 6y ago
    I guess it's an argument for and against it at the same time.
    - mdtusz 6y ago
      We had this argument recently at my workplace and dug into the pros and cons of both, ultimately settling or regular merges and no squash. The only real argument for squash-merges is that history remains linear and visually "clean", but if you want to see a "clean" history of only the merge commits, you just can just use the `--merges` option on the command line. Squash locally if you really want to or need to, but I'm a firm believer of disallowing it as the merge method for a changeset.
      - aaomidi 6y ago
        I have a less purist view on it personally. It doesn't really matter to me because I rather people commit more often, and if I really need history I can go check GitHub/etc.
yelloweyes 6y ago
definitely valuable for the linux kernel for bob's old ERP software company, really won't make a difference
djKianoosh 6y ago
I think the inexperienced developer simply hasn't had to personally dig through old commits/history to solve enough problems. There's likely a threshold (a 10000 hours type thing) where you've researched enough code history to value great commit messages and descriptions and docs/readmes, issue descriptions and comments etc. But how do we impart the importance of this to the other devs around us that will make it stick? Past "war" stories?
- cutemonster 6y ago
  Maybe let them maintain a 20 years old project with unusual behavior and requirements, and nice helpful 20 years old commit messages?
mcv 6y ago
Exactly. I always include the ticket or user story it's related to. It's a small effort, and if ever in the future someone finds themselves looking at this change and wondering what it's for, they can easily find the context. I seem to be the only one in my team doing this, though. (Obviously I also include a short but meaningful description of the change in the commit message itself. Again, not something everybody always does.)
flir 6y ago
I tell them that if you make two related changes, in two different parts of the codebase, the commit message is the only thing that "binds" them, and should be approached as if it was a comment. I guess I'm saying that commit messages are comments but with more flexible scope. (Now if I could just get them to squash, rebase and rewrite commit messages before publishing...)
_bxg1 6y ago
As a relatively young developer, I have to ask, are comments not a better place to document context? Commit messages are much less discoverable to me than comments when I'm looking at a piece of code. I usually put the "why" in comments and the "abstracted what" in commits. Enough info for someone to quickly rule whether or not a commit could have introduced a given bug, since that's usually what I'm looking for when I'm going through commit history.
- btschaegg 6y ago
  It's different context. If you're explainig why you write a piece of code the way you do, a comment is most certainly helpful. If you're explaining, why you're changing it the way you do, that's where the commit message shines. That's not to say you can't do both for intricate problems. And there are certain things you'll likely don't want to see inside your codebase (like references to bug tracker IDs and so on), which are IMO perfectly fine in a commit message. On the discoverability: Do you use `git blame` much? Because in projects that live a long time, that will most likely be the way you'll discover commit messages the most. And it is very handy in one of those WTF moments to see why and how a particular piece of code was altered, as opposed to "update" or "improve logic". Also: On your notion of "abstract what": That's supposed to be your commit's subject line. The rest of the message then will be the "why". I like to think of it as an email to some future maintainer (e.g. me in a year) on why it was necessary to change a piece of code. Edit: It's also important to see the differences workflow between your project and Linux, which Git was originally built for. In Linux, your change most likely is an email to some maintainer. If it sucks, your code won't be merged. And there's something to be said about being able to vocalize your reason for changing code. I still get the impression that many people who riff on the "return on investment" part of commit messages don't factor in that you're very likely not understanding a problem if you cannot describe it readably in text.
btschaegg 6y ago
I absolutely agree with you, but I'd like to point out that singling out "young programmers" here does not do this topic justice. This also goes for certain programmers that have been in the industry for decades. And if you deal with one of those, you'll find that they are even less likely to change their practices, so I'll take an impressionable young programmer to convince any day of the week. Of course, this topic extends to many other practices, such as using descriptive variable names, writing good comments and documentation (instead of the Captain Obvious approved ones), designing good APIs,…

technics256 6y ago

Where can one learn the art of excellent commit messages and when to rebase, etc?

dasil003 6y ago
This is a good start: https://chris.beams.io/posts/git-commit/ https://chris.beams.io/posts/git-commit/
- teddyh 6y ago
  See also: • https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst?id=HEAD https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/lin... • https://git.wiki.kernel.org/index.php/CommitMessageConventions https://git.wiki.kernel.org/index.php/CommitMessageConventio...
  - u801e 6y ago
    This is another good reference: http://who-t.blogspot.com/2009/12/on-commit-messages.html http://who-t.blogspot.com/2009/12/on-commit-messages.html
deleted 6y ago
[deleted]
g-b-r 6y ago
There's no "excellent", it's all opinions. Just look at the "imperative" that almost everyone recommends, try for enough times to cherry-pick commits that claim to do something and you'll realize how misleading they are

nullc 6y ago

> about how a code base "is crap" Translation: "Not written in the particular arbitrary style that I'm used to", of course if it were written in that persons preferred style another arbitrarily selected novice would call the result crap. I've found this to be almost universally true especially when the claim is given forcefully but not immediately backed up with a litany of actual user-impacting serious problems. This is not to say that code can't be crap, but generally people with the wisdom needed to make that determination know better than to waste their time yelling about it and know enough to suggest how to make it better instead. They recognize that good code can be written in a multitude of styles and that there is very little objective evidence for most style choices vs most others. Or, at least, they know enough to limit their forceful remarks to the most objective considerations-- such as code which is actually a source of frequent problems. > Taking the time to rebase, cleanup, and explain your changes in detail will pay huge dividends for any long-lived project. I've literally had successors write me a thank you note for a commit message from over a decade ago because I take this so seriously. Likewise, though more frequently I've been frustrated to see people make grave errors "fixing" correct code that they would have understood if they bothered to look at the message on the commit which introduced the "error" (or read the adjacent comment). The culture of writing good, informative commit messages and comments needs to go hand in hand with a culture of reading them. Neither works in isolation.

zabzonk 6y ago
> Not written in the particular arbitrary style that I'm used to Like "arbitrary styles" such as "a function shall not be 500 lines long".
- trade_unionist 6y ago
  Arbitrary like don't use reflection when a dll will do.
- Retric 6y ago
  An individual function can quite reasonably be 500 lines long. A giant case statement handling routing is one example. More controversially, if I am gong to need to do a lot of ugly compatibility hacks then I prefer to consolidate them and thus keep most functions clean.

justapassenger 6y ago

This so, so much. Too many people think that commit message is to explain HOW you did something. Unless you did something extremely clever (and in any commercial project, 99% of clever solutions are wrong - simple is the king), it should need more than few words. WHY you did it this way is the most important part. Given known and understood set of constrains, a lot of engineers will come up with similar solution, or at least understand it. And you can’t work effectively on something you don’t understand. Not having this context is reason for so many rewrites. Developer thinks a solution is supper crappy, goes to rewrite it, with grand vision. Only to learn along the way about all the edge cases and reasons for hacks.

tmh88j 6y ago
>Too many people think that commit message is to explain HOW you did something. >WHY you did it this way is the most important part. What was done is better suited for the commit message than how and why it was done, in my opinion. The latter two are better explained by comments in the code. I agree that why something was done is important for future reference, but when I'm tracking down code changes I'm looking for hints of the change itself. Understanding why comes next once you have the commented code in front of you to reference.
- rootusrootus 6y ago
  > The latter two are better explained by comments in the code Totally agree. Commit metadata is nice to have, but ultimately I think good code mostly explains "how" by the code itself, and "why" should be comments. Especially for local context, where the why has to do with some other bit of code. Individual commit messages are also secondary to the pull request merge commit, which should have a better explanation of the goal, or tie it to a task, etc.
- nemetroid 6y ago
  Requirements change over time, and so do the "why"s. So unless the code base is your primary documentation for requirements, "why" comments in the code can be dangerous: while outdated "what" comments can be determined as such by reading the code, there is no way (from the code itself) to determine whether a "why" comment is still accurate. A "why" comment in a commit message, on the other hand, only tells you what the "why" was at that time, something that cannot become outdated.

musingsole 6y ago

Yeah, but 99% of projects aren't anywhere close to long lived. Most products fail to launch. Most products that launch shutter within a few years. Having a code base survive long enough in close enough to its original state for a commit message to be meaningful a year later is unlikely outside of a few cases. Also, this is all predicated on the business case for the software being well understood that it could be written out beforehand by a entry level engineer. Which is not a situation I've seen outside of a processor design house. Otherwise, your thinking for this or that choice will be built on shifting sand anyway.

yxhuvud 6y ago
On the other hand, most people don't work at those short-lived projects. The vast majority of people work for profitable companies that have plenty of long lived code.
dredmorbius 6y ago
Short-term coding practices produce short-lived code. Predetermining code longevity is challenging.
u801e 6y ago
> Yeah, but 99% of projects aren't anywhere close to long lived. Most products fail to launch. Most products that launch shutter within a few years. Having a code base survive long enough in close enough to its original state for a commit message to be meaningful a year later is unlikely outside of a few cases. A lot of companies run code in production that was written years if not decades ago. Being able to look at the commit history and blame output helps in terms of getting some context about what was done and why it was done they way it was when the original authors have long since left the company. In my company, we still have some code written back in 2005 still running in production.

deleted 6y ago

[deleted]

yxhuvud 6y ago

Another thing those juniors are seldom good at, is knowing how to refactor an existing old code base. Which is not surprising, as everything they worked on during education is new code. Knowing how to change a code base from one abstraction to another is a skill that often take many years and lots of mistakes to learn.

sushshshsh 6y ago
Yet another boomer generalization designed to sow biases against hiring younger people. At what age am I allowed to become a senior, oh wise one?
- abraae 6y ago
  "Junior" is about experience, not age. You can be a junior developer at age 30, or a sage by that same age.
- bombela 6y ago
  We really gain skill for this over time. As I gain experience, I find that I understand in more details existing codebases. This increased my chance of a successful refactoring. Especially when replacing a core abstraction without a full rewrite.
- mech422 6y ago
  Usually senior is 5+ years experience... At what age did you start working, oh snarky one ?
- eggsmediumrare 6y ago
  The tech industry has a lot of problems, but bias against hiring younger people is not one of them.
- yxhuvud 6y ago
  Which part of my answer gave the idea that this is about age? FWIW, academia have never been good at teaching these skills, so the answer to your question is "You'll stop being junior with regards to refactoring complex code bases whenever you have enough experience of refactoring in big old code bases". Mentors pushing you in the right direction can also help. But this is very much a skill acquired by actually doing.

BurningFrog 6y ago

The maybe most common problem with programmer comments or commit message is what I call "Assumed Context". When you spend a few days deep in a problem, it's very easy to explain the finer details of it while forgetting the big picture of what does this module even do, what real world problem were we fixing, etc, because that has become completely self evident to you. It's a bit like giving a street address without saying what city it's in. I have trained myself to look at both code and comments in a "what if I was a new hire 6 months from now" mode, and it's an indispensable tool for me.

LeonidBugaev 6y ago

Head of Engineering with 15 years of experience here. If found that when we starting using Github flow, with pull-requests and etc, commit messages stopped really matter, in favour of PR descriptions. Plus when you use "squash" strategy, and use PR description as commit message, history looks great. When you look at commit history through Github tooling, all PR ids turned into links, and it is very easy watch for the history. Additionally you have a good integration with Github features, like discussions (which sometimes as important as description itself). Yes it is a vendor lock-in, but lets be frank, Github most likely will survive your project.

gregmac 6y ago
The commit message with a good PR description is okay, but for any sizable code change still doesn't provide full context for an individual piece of code (git blame). Either the PR description is massive -- in which case it's hard to read and tell what applies where -- or it glosses over the detail that's necessary. The thing is this isn't obvious why it's useful until you don't have it. I don't do it often, but the things that make me go back looking through git blame and history are trying to identify where hardcoded constants came from, or when (time or version) a particular bug was first introduced and why. This is only necessary when there aren't decent comments in the code already, and in my experience, the types of developers that don't put in these comments are also the ones that don't make highly detailed PR descriptions. Good commit messages is also a hurdle, but an easier one to get over than highly-detailed PR descriptions. On top of that you get all the other significant downsides of a squash merge strategy (eg: not being able to tell the difference between a local branch being merged or not pushed; confusing merge conflicts if you ever merge branch->branch before merging one to master). As an aside, IMHO, "clean history" is not at all a useful feature. Only developers are looking at git log to begin with, and they are quite capable of using `git log --merges` (or equivalent GUI operation). I guess the most useful thing is to make a CHANGES file (release notes) -- but honestly, the wording is different anyway (eg, "Fixed several minor UI issues" is adequate for release notes, but that might be across several PRs that contain more detail like "Fixed button alignment in modal dialogs", "Upgraded bootstrap to version x.y.z" etc). Go back and look at your PR descriptions from a year ago and see if you can make sense of them -- I bet the context of many will be lost.

secondcoming 6y ago

Well, Linux's commit messages kind of have to be descriptive since Linux is an Open Source project that doesn't have (that I can see anyway) an issue tracker or other management tool. When you do have those, then it's the ticket that gives the why's and how's. The commit messages do not have to be essays. And, at least with JIRA, if you name your branch such that it starts with the ticket id, it automatically picks up any pushed commits for that ticket. It's very useful.

u801e 6y ago
> And, at least with JIRA, if you name your branch such that it starts with the ticket id, it automatically picks up any pushed commits for that ticket. It's very useful. I've been working at my current place of employment long enough to see them transition between several different issue trackers. The links to old issue tracker tickets no longer resolve, so it's definitely better to include a description of the issue directly in the commit message in addition to the link to the issue tracker.

mrisoli 6y ago

I write detailed commit messages for every single commit I make(even though commits would be squashed on merges), I write detailed PR descriptions that included before/after screenshots in multiple resolutions whenever relevant. Never once did I have any indication that someone took their time to read descriptions or commit messages. In my previous job, I received some feedback from my manager that some people complained about code quality of my work, I was dumbfounded, I have no problem with being criticised, but I at least wanted to be able to learn from it and adapt. I went back through every single PR I did at the company and found little to no comments and it made me feel personally attacked with very little evidence. I then went on my peers PRs and see what I could learn from them, most PRs included highly non-descriptive commit messages and descriptions often only included a link to a JIRA ticket which most of the time was only visible to their direct team members and not me. From that I took the position of being more demanding on not just code quality during reviews but also descriptions, I didn't manage to influence a single developer to improve documenting efforts. That was a major reason why I eventually left the company. I continue to be a believer in taking your time to write good commit messages, I have yet to collect dividends from it however.

systemvoltage 6y ago
Yep, no one ever reads them and the cost to benefit ratio is extremely low. Writing good comments is far more important. Don't explain what the code does - that's what the code is for, explain the why and the background information in the code. Additional, explain what the code does at the function level or at the module level - at a much higher abstraction level basically than the line of the code. No one ever looks at the commit messages when trying to figure out what the code does as it convolves history and state of the repository, having to contextually wrap your head around when and how this commit was added. Inline documentation? Perfect.
- 0xEFF 6y ago
  I look at commit messages quite often working on a 10+ year old code base. Bisect leads to the commit, the commit message explains why the change was made. I take the explanation from 10+ years ago and determine if the reason still applies today. Or, I bisect and there's a low quality commit from 10 years ago from a person long since departed that simply says "fixup" and I'm dead in the water.

ndesaulniers 6y ago

I feel like all of my kernel commits are 50:1 ratio of commit message explaining the bug vs lines of code changed. Each one feels like it's own blog post. One of these days I plan to do a talk on kernel war stories. So many WTF bugs over the years.

mister_hn 6y ago

I've worked with 20yrs+ senior Devs whose commit message is always something like 1 or 2 words sentence (think of "cleanup", "feature X done") and some of there work manually with diff-tools between their local copy of code and the for repository they check out on a different folder. If they're not satisfied with the incoming changes, they just overwrite them and push the overwrite back to repository. This has happened with SVN and also is happening with Git. Unfortunately you can't argue with those ones since are in lead position and there's no one with technical skills above them in the C-level who can say anything (we don't have a CTO or a CIO, just CFO and CEO who can't even use their own iPad)

mamon 6y ago
In theory, this could still work if one of those two words put in by lazy developers was a JIRA ticket number where all the details are described in length. Atlassian stack (JIRA, Bitbucket, etc.) even allows you to make those clickable links.
- mister_hn 6y ago
  Sure, but when your Jira tickets are also poorly described, you have zero ways to track what has been done
cutemonster 6y ago
> they just overwrite them and push the overwrite back to repository. I'm not sure I understand what they're doing -- they overwrite some of the changes in their local working tree, and push to the repo, without explaining what they did/what they changed or why?
- mister_hn 6y ago
  Exactly. They keep a folder which isn't git-sync'ed (they fear the overwrites), then git pull on another folder and with graphic diff tools (e.g. Meld), they compare the changes. If they don't like the changes, they simply recopy the files from the non-sync'ed folder to the git folder and push it (a cherry pick would be too hard for them)

aaomidi 6y ago

Until you use squash and merge. Suddenly commit messages become far less helpful.

nemetroid 6y ago
Yep, a good argument against squash and merge.
- aaomidi 6y ago
  I guess it's an argument for and against it at the same time.
  - mdtusz 6y ago
    We had this argument recently at my workplace and dug into the pros and cons of both, ultimately settling or regular merges and no squash. The only real argument for squash-merges is that history remains linear and visually "clean", but if you want to see a "clean" history of only the merge commits, you just can just use the `--merges` option on the command line. Squash locally if you really want to or need to, but I'm a firm believer of disallowing it as the merge method for a changeset.
    - aaomidi 6y ago
      I have a less purist view on it personally. It doesn't really matter to me because I rather people commit more often, and if I really need history I can go check GitHub/etc.

yelloweyes 6y ago

definitely valuable for the linux kernel for bob's old ERP software company, really won't make a difference

djKianoosh 6y ago

I think the inexperienced developer simply hasn't had to personally dig through old commits/history to solve enough problems. There's likely a threshold (a 10000 hours type thing) where you've researched enough code history to value great commit messages and descriptions and docs/readmes, issue descriptions and comments etc. But how do we impart the importance of this to the other devs around us that will make it stick? Past "war" stories?

cutemonster 6y ago
Maybe let them maintain a 20 years old project with unusual behavior and requirements, and nice helpful 20 years old commit messages?

mcv 6y ago

Exactly. I always include the ticket or user story it's related to. It's a small effort, and if ever in the future someone finds themselves looking at this change and wondering what it's for, they can easily find the context. I seem to be the only one in my team doing this, though. (Obviously I also include a short but meaningful description of the change in the commit message itself. Again, not something everybody always does.)

flir 6y ago

I tell them that if you make two related changes, in two different parts of the codebase, the commit message is the only thing that "binds" them, and should be approached as if it was a comment. I guess I'm saying that commit messages are comments but with more flexible scope. (Now if I could just get them to squash, rebase and rewrite commit messages before publishing...)

_bxg1 6y ago

As a relatively young developer, I have to ask, are comments not a better place to document context? Commit messages are much less discoverable to me than comments when I'm looking at a piece of code. I usually put the "why" in comments and the "abstracted what" in commits. Enough info for someone to quickly rule whether or not a commit could have introduced a given bug, since that's usually what I'm looking for when I'm going through commit history.

btschaegg 6y ago
It's different context. If you're explainig why you write a piece of code the way you do, a comment is most certainly helpful. If you're explaining, why you're changing it the way you do, that's where the commit message shines. That's not to say you can't do both for intricate problems. And there are certain things you'll likely don't want to see inside your codebase (like references to bug tracker IDs and so on), which are IMO perfectly fine in a commit message. On the discoverability: Do you use `git blame` much? Because in projects that live a long time, that will most likely be the way you'll discover commit messages the most. And it is very handy in one of those WTF moments to see why and how a particular piece of code was altered, as opposed to "update" or "improve logic". Also: On your notion of "abstract what": That's supposed to be your commit's subject line. The rest of the message then will be the "why". I like to think of it as an email to some future maintainer (e.g. me in a year) on why it was necessary to change a piece of code. Edit: It's also important to see the differences workflow between your project and Linux, which Git was originally built for. In Linux, your change most likely is an email to some maintainer. If it sucks, your code won't be merged. And there's something to be said about being able to vocalize your reason for changing code. I still get the impression that many people who riff on the "return on investment" part of commit messages don't factor in that you're very likely not understanding a problem if you cannot describe it readably in text.

btschaegg 6y ago

I absolutely agree with you, but I'd like to point out that singling out "young programmers" here does not do this topic justice. This also goes for certain programmers that have been in the industry for decades. And if you deal with one of those, you'll find that they are even less likely to change their practices, so I'll take an impressionable young programmer to convince any day of the week. Of course, this topic extends to many other practices, such as using descriptive variable names, writing good comments and documentation (instead of the Captain Obvious approved ones), designing good APIs,…