Great point. Well-placed documentation as to why an approach was not taken can be quite valuable.
For example, documenting that domain events are persisted in the same DB transaction as changes to corresponding entities and then picked up by a different workflow instead of being sent immediately after a commit.
Practically, it only encodes information that made it into `main`, not what an author just mulled over in their head or just had a brief prototype for, or ran an unrelated toy simulation over.
Still, "3rd dimension" code reasoning (backwards in time) has never been merged well with code editing.
I did say VCS, but I also don't know what Git is missing in this relation.
> Other VCSes did support graph histories.
How does Git do not?
> Still, "3rd dimension" code reasoning (backwards in time) has never been merged well with code editing.
Maybe it's not perfect, but Git seems to do that just fine for my taste. What is missing there?
Yes, git ain't the only one, but apart from interface difference, they are pretty much compatible in what they allow you to record in the history, I think?
Part of the problem here is that we use git for two only weakly correlated purposes:
- A history of the code
- Make nice and reviewable proposals for code changes ('Pull Request')
For the former, you want to be honest. For the latter, you want to present a polished 'lie'.
Which is a causal history, not a editing log. So I don't perceive these to be actually different.
This was made possible by using a DAG for commit storage and referencing, instead of relying on file contents and series of commits per reference. Merge behaviour was much smarter in case of diverging tip or criss-cross merges. But this ultimately was harder and slower to implement, and developers did not value this enough and they instead accepted the Git trade-offs.
So you seamlessly did both with a different VCS without splitting those up: in a sense, computers and software worried about that for us.
You can use different, custom merge-drivers (or whatever it's called) for Git to get the behaviour you describe here.
Whereas bzr just did the expected thing.
Or I do not understand what you mean with "the expected thing".
There's an inherent tension between honest history and a polished 'lie' to make the reviewer's life easier.
git tracks revisions, not history of file changes.
The VCS history has to be actively pulled up and reading through it is a slog, and history becomes exceptionally difficult to retrace in certain kinds of refactoring.
In contrast, code comments are exactly what you need and no more, you can't accidentally miss them, and you don't have to do extra work to find them.
I have never understood the idea of relying on code history instead of code comments. It seems like it's all downsides, zero upsides.
> The VCS history has to be actively pulled up and reading through it is a slog
Yes, but it also allows to query history e.g. by function, which to me gets me to understand much faster than wading through the current state and trying to piece information together from the status quo and comments.
> history becomes exceptionally difficult to retrace in certain kinds of refactoring.
True, but these refactorings also make it more difficult to understand other properties of code that still refers to the architecture pre-refactoring.
> I have never understood the idea of relying on code history instead of code comments. It seems like it's all downsides, zero upsides.
Comments are inherently linear to the code, that is sometimes what you need, for complex behaviour, you rather want to comment things along another dimension, and that is what a VCS provides.
What I write is this:
/* This used to do X, but this causes Y and Z
and also conflicts with the FOO introduced
in 5d066d46a5541673d7059705ccaec8f086415102.
Therefore it does now do BAR,
see c7124e6c1b247b5ec713c7fb8c53d1251f31a6af */