Why make it harder, and why make it impossible to update if there are other suggested alternatives that are available since whenever the commit was made?
Because there is no way for a commit message to become outdated or detached from what it talks about, both of which are very much issues with comments.
> why make it impossible to update if there are other suggested alternatives that are available since whenever the commit was made?
Because that doesn't really matter.
Ok, so maybe rather than have this file we should run “git log | grep BANNED” and build a list of functions from that? Or maybe we could change all error messages to be “go look at the commit history to work out why this happened”.
No? Maybe putting context in source files (or better yet, an error message!) rather than in a side channel like the commit message has value when it comes to understanding and updating, and it won’t be lost under the weight of future commits.
That's why it makes sense to describe the background and reasoning behind a change in a Git commit, instead of inside your source files as comments.
They are suggesting adding a more informative error, which may include a subset of that background and reasoning. An error message that points you to the functions you should use instead is infinitely more informative than one that says “this is banned. Bye.”
The commit message from 2020 with suggested alternatives might very well go stale. Does the author go and force a noop commit so they can document new best practice in a new commit message?
What if they think of another reason why one of the same functions should be disabled?