> Lesson #4: When you choose specific non-default settings, leave a comment or link to documentation/issues as to why, future people will thank you.
Put it in the commit message. There is no better place to put it. That is the exact point in time at which you have the most information about that exact change. Commit messages are cheap, be liberal with your words and links.
It drives me nuts to read commit messages of the form "fix", "fixed 2", "add test", "new var" and on and on. You took an hour to make the change, take a damn minute to save some future colleague a day of frustration.
I agree with you about the importance of commit messages, but the problem with using them in place of comments is that commit messages become much harder to find as the history becomes longer, as opposed to comments which will always be immediately visible for as long as they are relevant.
Git blame only shows you the last person that touched the line, not the person who introduced a breaking change to that line (but it wasn't caught for weeks/months).
Comments are just as cheap as commit messages. Why not both?
Git blame can also show you the last revision which touched a file since some revision. Git log on a file can show you all the revisions in which it was touched. Using these together lets you slice the history in many useful ways, and there are countless gui-based tools (git gui, for example) which also allow you to explore revisions.
Whereas the commit is immutably and ideally exactly about what it's about. There is no better time to capture the information in a way that perfectly connects it to what it's describing.
While commit messages are always there, they get lost. You fix a bug in your code, with a commit message. Later, you realize that this function is super reusable, so you move the function to another class in another file. Now, for all intents and purposes, the original commit message will never be seen again.
It's harder to find originals under such circumstances, sure. But I don't see this as a reason for never writing good messages, because a journal of intent is strictly better than a journal of physical amendments.
That something needs to be entirely perfect before being judged better than the status quo is the Nirvana fallacy.
I don't think anyone is arguing for "never writing good messages"; the point is that you can have both good commit messages and good comments, both of which are useful for different reasons, and you don't need to give up one to have the other.
It shows you the commit that introduced the current version of the line. That's what you want if you want to understand the current version of the line.
I feel like I'm missing something here. I hate this feeling of impending dumb.
Got it. It's still possible to keep stepping back through the history of that line to understand its exact history.
I also typically find most files have only a handful of commits of interest in their history, so scoping a git log to the file often gets me within spitting distance of the right commit, if someone took the time to write a good one.
Edit: which goes back to my original point, that the commit is the best time and place to snapshot the meaning of that time and that place.
I agree, but you must also concede that not all developers are as proficient at git as you and might not be aware of such debugging/detective techniques. These same developers tend to favor print statements for debugging instead of an actual debugger. Also, not every developer has the privilege of using a DCVS like git.
For them, a comment in the code could save a lot of time and hassle.
Commit messages are good, but the dogmatic anti-comment philosophy that Pivitol follows is overdone. Lots (I mean LOTS) of comments are redundant or can be fixed with better naming or organization. But comments shine when dealing with the "why" behind something. I would rather see a comment that says why a value is set to what it is than have to be a git historian.
Yes, when there's no better alternative, or when it's idiomatic (Go linters) or situationally appropriate (Spring libraries are immaculately commented).
But I emphasise "no better alternative" because I have seen comment rot and it sucks badly. The English language is pretty vast and can be usefully ransacked for names. Keyboards are cheap and autocompletion plentiful, so go hog wild with variable names. There are idioms, patterns, well-understood conventions and so on that allow you to avoid noise.
When you need a why, then absolutely give the why. But usually the need for an explanation is that the code isn't clear on its face and you should exhaust that possibility first.
This concludes today's reading from the Book of Annoyingly Doctrinaire Ex-Labs Pivots. Go in peace.
So this is something I want to fix about commit messages.
If you screw up and forget to add the documentation to the commit message, there is nothing you or I can do about it. And if the commit log is not uniformly useful in this way, then people start to discount the value of the commit messages.
And then I have to explain to people who keep cutting and pasting code around improperly are ruining our commit history. I often get a shrug.
The first part we could do something about, and I hope we do in the next version control system (there's always a next one). All sorts of metadata should be capable of being attached to a code commit. Some of it stuff we have been relegating to third party tools, which means you can't reason about it as a whole.
Did this commit get a green build? Did it have a code review? What PR was it in? Did we run any static analysis? Did we learn after the fact that this code doesn't solve the problem or is a bad solution?
If all of this is at my fingertips, I've got a better chance of getting a bunch of people (myself included) to have a broader understanding of the code, or at least an easier time getting familiar with it when I need to.
One is commit discipline. People care more or they care less, no tool can truly change that.
The other is how we collect information. I'm not convinced that version control systems are the right place for that, but I know others have explored it (eg. Fossil SCM). Github provides what is a de facto data store for a lot of such annotations through their APIs, I imagine Gitlab does similar.
Commit discipline is a wider issue, but building and relying on tools that require humans to never make an error does not scale.
People always screw up their commit messages. And once they do it they stop trying because if you can't be perfect you're just torturing yourself to try. If there's a way to fix them after the fact you can begin demanding that people have more commit discipline and make them go back and fix it if they don't get it right the first time.
I take it as a matter of Broken Window syndrome. You can try to keep them from getting broken but at some point you have to have a way to fix the ones that break.
I didn't mean to give the impression that I don't think better tools are needed, I do. I feel that automation is a gift: what gets automated gets done. Tools create paradigms of working.
What I was driving at was that better tools are one part of the triad of people, tools and ways that people work together with tools. Commit discipline will always be desirable, because no tool can recover a snapshot of my mind at the time I made the commit.
The existence of a feature is not the same as a solution to the problem. All of these little tools that exist in the git toolspace are not automatic. Every developer has to add it to their already pretty long set of git rituals.
That's bullshit. We can do better than this.
Point me to a git feature that works when I do 'git push' or 'git pull' otherwise I'm not interested.
I'm also not interested in hearing people imply that people aren't smart enough if the tool doesn't suffice, and there's a very, very large concentration of that sort of asshole in the Git community. I don't make my tool decisions based on what I am smart enough or not smart enough to get. I make them based on what I'm willing to teach, my anticipation of how often I will have to be preempted to support others who don't get it, and what I'm willing to juggle when a production issue has the entire management team hand-wringing on a day when I'm already having a bad day.
Give me stupid-simple and dead reliable or it's not helpful.
Put it in the commit message. There is no better place to put it. That is the exact point in time at which you have the most information about that exact change. Commit messages are cheap, be liberal with your words and links.
It drives me nuts to read commit messages of the form "fix", "fixed 2", "add test", "new var" and on and on. You took an hour to make the change, take a damn minute to save some future colleague a day of frustration.