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?
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.
Your source code should describe what the program should do today. It should not contain all historical artifacts about your source code, as it'll grow to big and unmanageable then. Instead, use Git to store temporal information, data that is about change and reasoning behind it. Git is basically a timeline, instead of hard facts of today.
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.
Totally agree, which is why nobody is suggesting adding the background and reasoning behind the change to the source file as a comment.
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.”
Code is evergreen, whereas a git commit represents a change at a single point in time. It will always be limited by the knowledge the author had available to them.
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?
> 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.
What if they think of another reason why one of the same functions should be disabled?
