5 ms·

I find it highly backwards that documentation on "what to use instead of X" is in the commit message disabling X. One _might_ do it and might remember to do it,

by jorl17 6y ago

I find it highly backwards that documentation on "what to use instead of X" is in the commit message disabling X. One _might_ do it and might remember to do it, but IMO it makes absolutely no sense for this not to be documented properly in code, as suggested by OP. 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.

capableweb 6y ago
> 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. 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 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.
- jorl17 6y ago
  > 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. 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.
blitz_skull 6y ago
I disagree. Commits messages exist for the very purpose of adding context to your code base. If you added <complex_function> for something that needs context, sure MAYBE add a comment, but I really pray that I'm going to find a few paragraphs disambiguating the problem within a git commit. If I'm _really_ lucky, maybe I find a PR number or Jira ticket reference as well. 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.
- barnaclejive 6y ago
  So, you are tied to Git for eternity to preserve documentation? Might work in practice for a long time, but Git is a version control system, not a documentation system.
  - dpedu 6y ago
    For developer documentation - yes, absolutely!
- laurent123456 6y ago
  What if that code is refactored, moved around and changed so many times that it's nearly impossible to find the "documentation" for the line you're interested in. I mean sure you could spend a few hours going though commit messages, but wouldn't it be nice if there was a simple comment next to the code that gives the info right away? Also commits shouldn't be changed so if you want to improve the doc and provide more details, well you can't.

by jorl17 6y ago

capableweb 6y ago

> 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. 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 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.

jorl17 6y ago
> 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. 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.

blitz_skull 6y ago

I disagree. Commits messages exist for the very purpose of adding context to your code base. If you added <complex_function> for something that needs context, sure MAYBE add a comment, but I really pray that I'm going to find a few paragraphs disambiguating the problem within a git commit. If I'm _really_ lucky, maybe I find a PR number or Jira ticket reference as well. 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.

barnaclejive 6y ago
So, you are tied to Git for eternity to preserve documentation? Might work in practice for a long time, but Git is a version control system, not a documentation system.
- dpedu 6y ago
  For developer documentation - yes, absolutely!
laurent123456 6y ago
What if that code is refactored, moved around and changed so many times that it's nearly impossible to find the "documentation" for the line you're interested in. I mean sure you could spend a few hours going though commit messages, but wouldn't it be nice if there was a simple comment next to the code that gives the info right away? Also commits shouldn't be changed so if you want to improve the doc and provide more details, well you can't.