5 ms·
I write my comments in commit messages because those are valid forever. A lot of times somebody will write a code comment, the code will be changed, but the com
by locallost 5y ago
I write my comments in commit messages because those are valid forever. A lot of times somebody will write a code comment, the code will be changed, but the comment not. This is a huge waste of time on so many fronts: writing the comment in the first place, and then confusing the subsequent developers with the wrong information. If you truly want to understand something, you can always check the change log, and find out why things are how they are.
Exceptions are e.g. if it's something exceptionally tricky or a hack of some kind that is kind of important. It doesn't happen all that much because the stuff I work on is simple. If I was going to do a lot of "commenting" I would prefer to write and update good documentation that gives an overview of how different things work together. The nitty gritty changes too often and is not that important in the grand scheme of things.
- deleted 5y ago[deleted]
- janaagaard 5y ago> I write my comments in commit messages because those are valid forever. Don’t they disappear when someone squash merges branch where a file is both renamed and changed (a lot)? Or, at least, when somebody decides to move to code to another repo, and doesn’t bother bringing the git history along.
- cerved 5y agosquash merge is evil
- usr1106 5y agoThe author should squash useless commits. A readable series of commits is put to review. At merging to a commonly used branch no more squashing.
- cerved 5y agoWhy? Why doesn't the author make commits that are not useless? Why squash everything into a single commit? Why not 2 commits, 3, 5?
- reidjs 5y agoI feel differently, why don’t you like it?
- zerocount 5y agoYep. I make a commit on every little change and every team I've been on makes me squash them on merge. Comments in Git commits are bad. Just comment the code and make sure the comments are updated while you're in the code. You can also look at them in a code review. The argument that they get outdated is easily remedied, but people just want to keep claiming they write 'self documented code.'
- AlexCoventry 5y agoEveryone has to be onboard for that to work. Lots of people just never look at comments because they don't trust them.
- Zitrax 5y agoGit commit messages and code comments serve very different purposes, I don't see any reason to try to use one for the other or opposite. To me both are important but for different reasons. I don't want to search the blame history of a line of code if a simple comment had been enough, neither would I want to primarily use code comments when bisecting.
- johnisgood 5y agoI dunno if he really meant that, or just said he is explaining the added functionality in detail. I do explain in the commit message the feature I have just added.
- u801e 5y ago> make sure the comments are updated while you're in the code. You can also look at them in a code review. People will invariably forget to update comments and unless the comments show up in context lines of the diff associated with a change, it's likely that reviewers will overlook the need to change them.
- Gibbon1 5y agoYou comment is a standard explanation for not having comments. Always makes me wonder why stale comments aren't flagged during code review? Seriously failure to update comments should eventually lead to constructive dismissal.
- jt2190 5y ago> … when someone squash merges… It depends on who the “someone” is I suppose. I typically squash my own commits, and as part of that I aggregate all of the commit messages into a single message with all of the relevant details (and leave out the “fixed typo” type stuff that’s not relevant.) From the complaints that people are raising here there must be dev shops where someone else decides to squash a bunch of commits and throw away the messages.
- interactivecode 5y agoThat’s horrible because the git commit messages are easily lost, disconnected or hard to find in any reasonably active codebase. For example as soon as you do a change and move a file it almost always disconnects from the previous change history. Whats even more difficult is searching through a code base when the documentation isn’t in or near the code. I don’t know any IDE or editor that makes it easy to search though git commit message and source code at the same time. On top of that, do you review git commit message in code review? Do you aks people to improve descriptions, typos and language in commit messages?
- cerved 5y agogit log --follow -p file edit: here's another git log -p -L:show_commit:builtin/rev-list.c
- sildur 5y ago> I don’t know any IDE or editor that makes it easy to search though git commit message and source code at the same time. Any editor from Jetbrains with the GitToolbox plugin does that.
- 9dev 5y agoCan second that. Having the commit message as a virtual comment on the end of the current line is immensely helpful in tracking changes. It’s like git blame on steroids.
- prometheon1 5y agoI also like seeing the commit messages in this way! In the case of VSCode this comes with the Git Lens extension.
- locallost 5y agoI don't understand how they are hard to find. It's trivial to find where the file was moved from. What I truly care about is why something is the way it is, what is the rationale behind it, how it works with other parts of the codebase, what problems it solves, what is tricky about it, what to pay attention to and so on. I don't care at all about the code that was written and an explanation to it because this I can read myself in the code. The best place I've found for this is a code commit because it can tie different parts of the codebase together and add a lot of context to a change. I commit heavily and don't squash. A long comment in a commit that contains all file changes related to a certain feature, bug or whatever adds a lot more information than a comment in one file. When other people do it, it helps me a lot more than chasing their (outdated) code comments throughout the codebase. But if that doesn't work for you, then don't do it. Just don't be dogmatic and dismissive. I accept there might be situations and codebases where this doesn't work.
- nine_zeros 5y ago> I write my comments in commit messages because those are valid forever. Only until someone moves a file to a new directory. Now this file shows up as a new file with no history. Also, you hope to never change your version control system because that change will erase the history. Relying on commit messages is sometimes just not good enough.
- cerved 5y agoNo it doesn't. At least git tracks and follow renames
- masklinn 5y ago> Only until someone moves a file to a new directory. Now this file shows up as a new file with no history. Git will usually be able to link the two back, unless the move was combined with a lot of changes, as it does not record moves but infers them. Even if it can't link them, the "creation" commit will visibly remove the old file, at which point you can... log / blame on the previous location and keep going. > Also, you hope to never change your version control system because that change will erase the history. Of course not, there are conversion tools between basically all VCS, and anyone tasked with such a migration who is not a complete goober will use them in order to maintain the historical record. At $dayjob we've got history spanning over 3 different VCS and more than 15 years, and that's including weird stuff like splitting and merging repositories.
- Zababa 5y agoSame thing here. At work I can see the history going back to 1995. And that's after migrating from something to Mercurial, and from Mercurial to git. Maybe that's not the case in all companies, but in the one I work at, the commit history is the longest-lasting information trail.
- yarky 5y agoThat's a great idea. I've been doing this just to rationalize my laziness, but now it makes sense. However, I'm not sure those are valid forever as you can simply delete the .git folder, can't you?
- u801e 5y ago> I write my comments in commit messages because those are valid forever. I try to write good comments and commit messages. Comments are typically along the lines of explaining what was done and how for a particular block of code or method. Header comments include a list of parameters, return values, side effects, class variables, etc. Commit messages explain what was done or changed and why.
- ajuc 5y ago> Header comments include a list of parameters, return values, side effects, class variables, etc. These are only useful for public stuff and in special circumstances in other cases. Sadly a lot of companies make stylecheck require them on every little private method which makes each file 50% longer for no reason and drown the really useful comments in noise. > Comments are typically along the lines of explaining what was done and how for a particular block of code or method. The problem with that is that the block of code that you explain will often call other code, and then that other code will change for other reasons (preserving the correctness but not the initial design that was in the comment) and then that explanation higher in the callstack won't be true anymore. It's nice to pretend we always check everything that calls our code all the way up when we change stuff, but in reality if tests pass and the code works - we often don't check for comments up the callstack. So the comments will drift away from the truth with time. Comments in commit messages are much more likely to be true than static comments in code (for example if you refactored some method signature as part of the change - every call site will have the updated commit message automatically). If you comment in the code manually - you will probably not notice that you have to change a comment block 5 lines above the changed function call - it won't even show in the diff - so the comment block won't be true anymore).
- fenomas 5y agoThis sounds like a recipe for write-only comments. The point of a good comment is to guide later development - to say "here's something you should know before editing this code". If you put information like that in commit logs, then that implies that anybody who updates any part of that codebase must first read every log for every commit near what they're editing. If they don't (and they presumably won't), they'll never see that "here's why we're not doing X" comment before they change the code to do X. Meanwhile, it's true that comments can drift away from truth over time, but putting them in commit logs doesn't change that in any way. An inline comment that's stale can be updated (and doing so is part of the job!). But a commit log comment that's no longer accurate will stay there forever, waiting to mislead anyone who finds it. The promise that it was accurate when originally written is of no practical use later on.
- codedokode 5y agoSo if you added several classes and functions, you describe them all in a single commit message? Probably you don't document them at all.
- 8note 5y agoCommit messages don't necessarily last as long as the code that they comment though. Changing revision control system or copying code from one package to another can lose them. The only durable documentation I've seen is in the source code