It seems pretty safe to assume a developer contributing C code to git itself would know how to use git blame (or the GitHub interface for it).
By that logic, a non-insignificant amount of (good) comments in code could be removed and people asked to "git blame the code and check out the commit that made it for the documentation". Of course this could be done, but it sounds ridiculous even typing it out.
If you're truly clueless as to what could be substituted for these commands, then you don't understand why they're banned. So our first step? Figure out why they're banned. And how would we sanely approach this? Probably by checking the commit message for _why that code is there in the first place_. That's a very safe, sane, and not-at-all backwards assumption. After you understand why it's there, a quick google search might help out if the commit message didn't already include information on alternatives.
Lastly, yeah, I totally agree a large amount of GOOD comments should be relegated to the git commits if all they're doing is adding additional context around a complex piece of logic. Comments do not exist to edifying a code base in any way other than context. They're too easy to let become stale, whereas a git commit will always reference exactly the code you're blaming.
So, I have to really disagree that it's ridiculous or in any way absurd. In fact, I think a lot of code suffers from NOT using git as a way to extend context around a code base. It's SUPER easy with most development environments to select a block of text and blame it. It's so easy that it's almost always my go-to to increase my context of what's been happening around a particular part of the code base.
Also commits shouldn't be changed so if you want to improve the doc and provide more details, well you can't.
Granted these concerns are probably less likely to apply to this particular file.
Perhaps they just felt that anyone contributing to git would already know why not to use those/what to use instead (but then there would be no need to ban them).
Might work in practice for a long time, but Git is a version control system, not a documentation system.
Yes, exactly. You want to understand how a codebase changed and evolved over time? Git is your friend. If you want the facts of the code today? The source code is your friend. That's why the way Linux and Gits Git repository method of storing history makes sense. See also https://news.ycombinator.com/item?id=26348965
Try navigating the Git codebase with a git-blame sidebar (probably VS Code has that somewhere) so you can see the history of the source files. If you wonder why something is what it is, you can checkout the commit that last modified it. Or go even further backwards and figure out in the context it was first added. If you truly want to understand a change, a git repository with well written git messages is a pleasure to understand and dig into.
100% agree. Though I don't mind if comments also leave historical information about the code. Can't be too much -- there is a delicate balance.
Do note, however, that you said it yourself: If you want the facts of the code today, go to the source code. In my opinion, the "facts of the code of git" are that functions X,Y,Z are "banned", but the code does not tell me why, or what to use instead. It just bans them. I would expect to see something in the code, not (just) in a git commit. It's also not that I can't google these functions (a couple of minutes will answer these questions), or that I should be experienced enough to know why they're evil, it's that it's IMO a reasonable, developer-friendly and good thing to do.
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?