If the comments are longer than the commit message, future-you is already paying for it.

If the comments are longer than the commit message, future-you is already paying for it.

This is for people who build things, move fast, and then reopen the same project 3 months later wondering what the hell the decision was. That is where time gets burned: not because the code is unreadable, but because the reason behind it is gone.

My contrarian take: long comments often mean the design is quietly doing too much work. Long commit messages are where the real decision should live.

That is also the line behind the 2 public guides people cite most here. Git’s patch guide says the log message matters as much as the code because future maintainers need the why, not just the how. Google’s C++ style guide makes the same point from the other side: comments should not just translate obvious code; either explain higher-level intent or make the code clearer instead.[S001][S002]

So the split is simple. Use comments for sharp edges, warnings, contracts, and weird behavior. Use the commit message for the decision: why this changed, what tradeoff was chosen, and what path was left behind.

One update is worth saving or sharing when it changes your next decision, not when it just dumps more detail. Send this to the friend you argue with about this: richer comments, or richer commit messages?