3 ms·

> This is a mistake — no one finds value in it, so it should be kept private. Just anecdotal, but I disagree vehemently. In my experience, an easy way to follo

> This is a mistake — no one finds value in it, so it should be kept private. Just anecdotal, but I disagree vehemently. In my experience, an easy way to follow Chesterton's fence ( to figure out why a piece of code is the way it is before modifying it's behaviour), is to understand the decision making process that was being followed and not just the blob of code that added it (Even more so on older repos where the original author may not be around). Many a times, it becomes obvious that the code was written under a very different understanding of the what the system evolved to be, and as such can be changed accordingly, and inversely that the code makes certain strong assumptions when written which hold true even today. This is why as a thumb rule, especially for junior developers just getting started with git, I spend time on getting them to understand good git commit messages instead of 'git add . ; git commit -m "some code"' because I've seen a tonne of value retrospectively in this.

someweirdperson 4y ago
> [...] I spend time on getting them to understand good git commit messages instead of 'git add . ; git commit -m "some code"' Decisions could also be documented explicitly, explaining the pros and cons of possible solutions to future readers. However, in absense of this, commit logs may contain this information, better than nothing. But with all the commits kept from development the logs will contain a significant amount of non-interesting information, and make the history hard to read a few years later. And reading the log to find something will get slowed down by explanations that should be in docunents or comments in the code.
- masklinn 4y ago
  > Decisions could also be documented explicitly, explaining the pros and cons of possible solutions to future readers. Such decisions would be documented in the commit log. Optionally linked to an expanded version off-log (e.g. mailing list threads, issues, tickets, ...)
lamontcg 4y ago
> understand the decision making process that was being followed This should be documented in the PR in human language, hopefully with some backwards and forwards and questions asked and answered. I'll frequently go back and document why the PR wound up the way it did even after everything has been merged and shipped because some discussion a day later makes me realize that the information had never been captured. And those can be options that were never in the commit history because they weren't the path that was taken. Then a few years later you can read the PR and see that there were different options, that some of them were rejected as not meeting the actual requirements, there might have been concern about breaking changes, the very issue that has cropped up later might have been anticipated but a simpler solution was used on the expectation that the complicated solution wouldn't be necessary (and now it is necessary). The "why" of a change is a lot more than the history of the person typing on the keyboard and making commits, there's a whole lot of thinking that goes into a change which is never reflected in a single line of code.
gorgoiler 4y ago
You’re absolutely right. Version control should show the changes to the code as well as the reasoning for making the change. Our only disagreement is that you want to track that using the commits that led up to the final idea being complete, whereas I delete the history and rewrite the story of the idea, what was there before, what’s changing, and why in the final commit message. When the problem you want to solve is to provide a historical account of new features for future developers fixing bugs — often you, yourself — then a written document of a few paragraphs, right there in the git log/ blame, provides the highest signal.

someweirdperson 4y ago

> [...] I spend time on getting them to understand good git commit messages instead of 'git add . ; git commit -m "some code"' Decisions could also be documented explicitly, explaining the pros and cons of possible solutions to future readers. However, in absense of this, commit logs may contain this information, better than nothing. But with all the commits kept from development the logs will contain a significant amount of non-interesting information, and make the history hard to read a few years later. And reading the log to find something will get slowed down by explanations that should be in docunents or comments in the code.

masklinn 4y ago
> Decisions could also be documented explicitly, explaining the pros and cons of possible solutions to future readers. Such decisions would be documented in the commit log. Optionally linked to an expanded version off-log (e.g. mailing list threads, issues, tickets, ...)

lamontcg 4y ago

> understand the decision making process that was being followed This should be documented in the PR in human language, hopefully with some backwards and forwards and questions asked and answered. I'll frequently go back and document why the PR wound up the way it did even after everything has been merged and shipped because some discussion a day later makes me realize that the information had never been captured. And those can be options that were never in the commit history because they weren't the path that was taken. Then a few years later you can read the PR and see that there were different options, that some of them were rejected as not meeting the actual requirements, there might have been concern about breaking changes, the very issue that has cropped up later might have been anticipated but a simpler solution was used on the expectation that the complicated solution wouldn't be necessary (and now it is necessary). The "why" of a change is a lot more than the history of the person typing on the keyboard and making commits, there's a whole lot of thinking that goes into a change which is never reflected in a single line of code.

gorgoiler 4y ago

You’re absolutely right. Version control should show the changes to the code as well as the reasoning for making the change. Our only disagreement is that you want to track that using the commits that led up to the final idea being complete, whereas I delete the history and rewrite the story of the idea, what was there before, what’s changing, and why in the final commit message. When the problem you want to solve is to provide a historical account of new features for future developers fixing bugs — often you, yourself — then a written document of a few paragraphs, right there in the git log/ blame, provides the highest signal.