3 ms·

> documentation tends to be for users. There is user documentation and there is technical documentation. Both are very different. Unless you have a lib, framew

> documentation tends to be for users. There is user documentation and there is technical documentation. Both are very different. Unless you have a lib, framework or such, in which case it's more or less the same. > but if you're going to be tracking changes in git anyway Yes, it's a technical system for tracking changes, not documenting those changes on the developer-level. > so people don't have to hop to a different system to get a quick understanding of the commit? Because for any meaningful complex product you need to do that anyway. commit-messages are just the bare minimum of ways to document. Though, of course, you can make more use of it, including it in some semi-automatic changelog and such. But usually it's not worth the hazzle.

BanazirGalbasi 3y ago
> tracking changes, not documenting those changes Documenting changes is part of tracking them. Yes, there is the code itself, but explaining those changes allows for following the development path. Do you expect everyone to read every line of code to understand every commit? > commit-messages are just the bare minimum of ways to document Single-line messages, yes. Multi-line commit messages are plenty for commit messages because they let you add more context about the changes. I'd like to point out that it's possible for there to be multiple commits for a single issue - maybe the first one didn't fix it, or maybe there's multiple components being fixed. Simply pointing back to the issue won't give enough relevant information about each commit, it will simply say what the group of commits as a whole is supposed to do. If it turns out that fixing that issue caused others to occur, then the individual commit messages are going to be more useful for diagnosing the new problem than a single lump issue conversation will be. I agree that there should be more documentation for a project than just git commits, I just think you're wildly estimating how useful commit messages really can be.
- PurpleRamen 3y ago
  > Do you expect everyone to read every line of code to understand every commit? Do you expect everyone to read every commit? I get the impression you have the wrong focus.

BanazirGalbasi 3y ago

> tracking changes, not documenting those changes Documenting changes is part of tracking them. Yes, there is the code itself, but explaining those changes allows for following the development path. Do you expect everyone to read every line of code to understand every commit? > commit-messages are just the bare minimum of ways to document Single-line messages, yes. Multi-line commit messages are plenty for commit messages because they let you add more context about the changes. I'd like to point out that it's possible for there to be multiple commits for a single issue - maybe the first one didn't fix it, or maybe there's multiple components being fixed. Simply pointing back to the issue won't give enough relevant information about each commit, it will simply say what the group of commits as a whole is supposed to do. If it turns out that fixing that issue caused others to occur, then the individual commit messages are going to be more useful for diagnosing the new problem than a single lump issue conversation will be. I agree that there should be more documentation for a project than just git commits, I just think you're wildly estimating how useful commit messages really can be.

PurpleRamen 3y ago
> Do you expect everyone to read every line of code to understand every commit? Do you expect everyone to read every commit? I get the impression you have the wrong focus.