4 ms·

Good stuff here. I joined a team years ago that had a pretty solid and consistent practice of writing thorough commit messages, while still being somewhat conci

Good stuff here. I joined a team years ago that had a pretty solid and consistent practice of writing thorough commit messages, while still being somewhat concise. We made good use of the space to also include links to reference docs/tickets/etc. for follow up. This was incredibly useful in the long run when we’d be bisecting changes to identify a bad commit or just understanding the history of a small but important change (eg: why did we set this flag?). Its effectively free documentation space that costs nothing to add detail to.

eviks 2y ago
It costs having to bisect to find it instead of just reading the code/doc
- appplication 2y ago
  I am 100% against overdoing commit messages for the reason that if it’s important enough to document then it should be in the code or docs, not a commit message. They’re just not a functionally discoverable form of documentation. Commit messages can be good for providing context as to why something is changing, but all context as to how it works should be formalized elsewhere. For example, a commit message that tells you how something works could immediately become misleading when functionality is changed in the future. And you’d have to consume the whole chain of commits to begin to understand that. Personally, I overdocument everything with verbose comments in code that explain things in detail, as well as the context, thought processes, and assumptions behind it. I have found that it creates a codebase you can read more like a book, which makes it so much easier to build context. I haven’t measured it exactly, but if I had a 1000 LoC file, I’d say 600+ lines would be comments.
  - captainkrtek 2y ago
    My comment was not meant to intend commit messages be the sole form of documentation. I am also a big fan of good code comments, docs, etc. Just prefer a lengthy commit message (when warranted) over short meaningless messages (eg: “changed thing”). Most useful in my experience is quickly grepping git log for keywords if im searching for a relevant change.

eviks 2y ago

It costs having to bisect to find it instead of just reading the code/doc

appplication 2y ago
I am 100% against overdoing commit messages for the reason that if it’s important enough to document then it should be in the code or docs, not a commit message. They’re just not a functionally discoverable form of documentation. Commit messages can be good for providing context as to why something is changing, but all context as to how it works should be formalized elsewhere. For example, a commit message that tells you how something works could immediately become misleading when functionality is changed in the future. And you’d have to consume the whole chain of commits to begin to understand that. Personally, I overdocument everything with verbose comments in code that explain things in detail, as well as the context, thought processes, and assumptions behind it. I have found that it creates a codebase you can read more like a book, which makes it so much easier to build context. I haven’t measured it exactly, but if I had a 1000 LoC file, I’d say 600+ lines would be comments.
- captainkrtek 2y ago
  My comment was not meant to intend commit messages be the sole form of documentation. I am also a big fan of good code comments, docs, etc. Just prefer a lengthy commit message (when warranted) over short meaningless messages (eg: “changed thing”). Most useful in my experience is quickly grepping git log for keywords if im searching for a relevant change.