5 ms·
One thing I always want to tell people about commit messages: There’s no length limit. In fact, write as much as you can. Go crazy. Write some more. Explain.
by jordigh 8y ago
One thing I always want to tell people about commit messages:
There’s no length limit.
In fact, write as much as you can. Go crazy. Write some more. Explain. Talk about how your day went. Tell us how you found the problem. Put benchmarks that show why your change makes things faster. Show the stack trace or test output that you’re fixing. Quote other people. Put an email chain in the commit message.
In a well-curated commit history, commit messages become source-level documentation available via an annotate/blame operation. Most people hate writing documentation, but commit messages are about the only time when our tools force us to write something. Take this opportunity to really write something. It’s the only time when writing is really required in any way. There’s no need for a length limit because most of the time the commit messages are hidden away, and most interfaces will hide the full commit message anyway (or can easily be configured to do so).
If you want practice jamming lots of information into a small amount of space, that’s what the first line of the commit message is, but after that, don’t feel constrained by length limits.
These are examples of my favourite kind of commits:
https://www.mercurial-scm.org/repo/hg/rev/4fb2bb61597c?style=gitweb https://www.mercurial-scm.org/repo/hg/rev/4fb2bb61597c?style...
https://www.mercurial-scm.org/repo/hg/rev/ed5b25874d99 https://www.mercurial-scm.org/repo/hg/rev/ed5b25874d99
https://www.mercurial-scm.org/repo/hg/rev/1423ff45c322 https://www.mercurial-scm.org/repo/hg/rev/1423ff45c322
https://www.mercurial-scm.org/repo/hg/rev/dd028bca9221 https://www.mercurial-scm.org/repo/hg/rev/dd028bca9221
https://www.mercurial-scm.org/repo/hg/rev/8d5584d8345b https://www.mercurial-scm.org/repo/hg/rev/8d5584d8345b
- robocat 8y agoFrom your first link: I think that comment should be placed as a source code comment near the source code: "preferedchunksize = 32768". I think magic numbers should be described at the point they are defined, or at least put a link (in a source code comment) to why the music number was chosen....
- jordigh 8y agoThat would be a lot of clutter. When you're on a codebase where people bother writing commit messages, reaching for blame/annotate output becomes second nature and reveals so much about your code. It's just as good if not better than comments, because every line in your source now has a comment.
- tln 8y agoIn fact, every line of your source has several comments! Which may or may not really apply! BOTH are needed IMHO, comments must be able to communicate knowledge a reader of the code-as-a-whole needs to know, and commit messages must be able to communicate knowledge a reviewer of the change needs to know.