91–100 of 406 posts
I agree commit messages are the most important form of documentation. But I disagree about the format. I prefer commit messages like: JIRA-123 one-line 80-char-at-most description Long description if needed (but preferably keep it in JIRA).
For better or worse, my experience as a GitHub cofounder and author of several Git books (Pro Git, etc) is that the Git commit message is a unique vector for code documentation that is highly sub-optimal. The main issue is that most of the tooling (in Git or GitHub or whatever) generally only shows the first line. So in the case of this commit example would be the very simple message of a generic "US-ASCII error" pro…
I am terrible at git on the terminal, but with IntelliJ or emacs and magit, I can trivially find every commit ever to change a file, and easily navigate the commits to see every full commit message. It's not hard when you use a proper tool, and I have a feeling almost everyone has something like that?! Do you really try to stick with the git CLI and memorize hundreds of commands and flags?? Why?!
That first line of the commit message is most important so that `git log` can address chesterton's fence. And IMHO in this case the committer whiffed. The key is not to put what you did in that first line, but why . Anyone interested in what can just look at the code, perhaps via a diff. So something like "nginx .conf files must be in us-ascii" Then "changed blahblah.erb to remove nonbreaking space character" Then th…
Great quote and life advice, will definitely steal this! Thanks!
For better or worse, my experience as a GitHub cofounder and author of several Git books (Pro Git, etc) is that the Git commit message is a unique vector for code documentation that is highly sub-optimal. The main issue is that most of the tooling (in Git or GitHub or whatever) generally only shows the first line. So in the case of this commit example would be the very simple message of a generic "US-ASCII error" pro…
Well, `git` is still the primary way I interact with a git repository, and `git log` shows the entire commit message by default. So I don't run into this problem. If some "modern" git frontend is only capable of displaying the first line of a commit message, then this is a problem with that tool, not git itself. (I'm also not convinced this is a limitation of all modern tooling...)
I had a terrible time when someone used "smart quotes" (beautified Office quotation marks) in a configuration file. I believe this was only possible because they copied it from Outlook.
>smart quotes I never understood why a "stylistic" choice requires separate characters. If we don't need a serif and non-serif version of every character and instead leave it to the software, why can't we do the same with the "smart" quotes?
Essentially zero people read complex commit messages. Do with this information what you will. 9/10 the code already is documentation enough for what the code currently does, if you need to go back through history then look at the commits. The messages are generally noise. I've literally never cared _why_ someone made a change, I can see the change, I can see the effect of the old and new code. Rarely, if ever, has th…
> Essentially zero people read complex commit messages I don't think that's true. I worked in support doing break/fix and outage response work at a large organization. That means constantly dipping into codebases I'm utterly unfamiliar with. Often there is complexity, un-obvious elements, previous incorrect attempts at a bugfix and so on, where understanding what the author intended can save literal hours of examinat…
The problem with that it that you are relying on an inherently unreliable source of information - a human to enter details which may or may not lead you to the correct path.
The code doesn't "lie". Just read it and the current issue and work from there.
I think the disadvantage with this style of documentation is you can't really alter the commit message after it's written. (I mean you could obviously with "rebase" but are you really going to alter something written one year ago, already merged to "main", and cause a bunch of pain with everyone's feature branch etc.?) Compare that with documentation stored in a .md file, or even a Wiki or even Confluence. My colleag…
> I think the disadvantage with this style of documentation is you can't really alter the commit message after it's written. That is not a disadvantage. The commit is a historical record, if I come back to that commit 3 years later I want to know its purpose in the context it was in, I don’t want a whitewashed history. > Compare that with documentation stored in a .md file, or even a Wiki or even Confluence. My colle…
OP's point is that, while commit message is indeed a historical record, documentation isn't (or shouldn't).
If you double commit message as documentation, it would cause issues like wrong information confusing or misleading future readers because it's non-editable.
For better or worse, my experience as a GitHub cofounder and author of several Git books (Pro Git, etc) is that the Git commit message is a unique vector for code documentation that is highly sub-optimal. The main issue is that most of the tooling (in Git or GitHub or whatever) generally only shows the first line. So in the case of this commit example would be the very simple message of a generic "US-ASCII error" pro…
> Even if you're _very good_ at Git, finding the correct invocation of "git blame" (is it "-w -C -C -C"? Or just _two_ dash C's?) to even find the right messages I am terrible at git on the terminal, but with IntelliJ or emacs and magit, I can trivially find every commit ever to change a file, and easily navigate the commits to see every full commit message. It's not hard when you use a proper tool, and I have a feel…
For better or worse, my experience as a GitHub cofounder and author of several Git books (Pro Git, etc) is that the Git commit message is a unique vector for code documentation that is highly sub-optimal. The main issue is that most of the tooling (in Git or GitHub or whatever) generally only shows the first line. So in the case of this commit example would be the very simple message of a generic "US-ASCII error" pro…
> Even if you're _very good_ at Git, finding the correct invocation of "git blame" (is it "-w -C -C -C"? Or just _two_ dash C's?) to even find the right messages I am terrible at git on the terminal, but with IntelliJ or emacs and magit, I can trivially find every commit ever to change a file, and easily navigate the commits to see every full commit message. It's not hard when you use a proper tool, and I have a feel…