It's controversial because it is false. Looking at the code gives you what is happening. The why is almost impossible to put inside. The developers have been trying to cram more and more context into the codebase since the first assembly comments were written. And still we fail.
That's just bad code, and yes, that happens. But if you can write it in a commit message you can capture it somewhere else that people will actually see without having to root around in a completely separate system.
In my experience the implementation is always hairy and because of the immensely complex stacks we are using in modern dev it is full of all kind of weird workarounds. And we don't really have good place to put - I wrote it in this insane and stupid way because some other module that I have no control over crashed except the commit message.
And anyway any project that uses issues tracking also has a lot of context in the issue tracking - by your point of view the developer writing the piece of code that needs commenting should somehow cram the whole issue inside the codebase. We are already using external system anyway - there is no harm in putting information there - the system won't be complete without it anyway.
In my experience (and I have been on any kind of failed at any scale) there is no good way to manage information and context - just slightly less terrible ones.
But if you have a piece of insane code, especially if it's fairly localised, why is it superior to explain it in a commit message and not a comment right there next to it? Save people the head scratching.
And yes - I do exactly think that the developer should cram the whole issue in the codebase! Those are your acceptance tests, or explicit representations of use-cases or strategies, or service layers, or at the very least some comments lamenting what would otherwise be inscrutable. If your codebase doesn't have a first-class way of describing what it does and why, I don't think it's well-factored.
I totally agree that it's easy to mess up, I just continue to think this terrible workflow of externalising key information about code and why it exists is fundamentally defeatist. I don't think we should settle for it.
That is a limitation of the tooling we have unfortunately. Every line in the text files that is not code increases the cognitive load of the person when not directly relevant. And unfortunately a lot of development is done on laptops or otherwise screen restrained machines.
I agree in principle that the metadata and code should be linked and easily pop in view on demand. But that is not how the tooling currently works and we find only crutches.
This is cool paradigm that could make amazing startup. Add in some LLM for buzzword to hook investors. And actually LLM that can trawl all the current sources of knowledge and spitting a one paragraph to glance what and why is going on could even work.
But we can't do it while constraining to text files. We need the equivalent of hypertext for code ... and it will be mess in the end.
