On 08/22/2013 11:16 AM, Chris Evich wrote:
All,
Chris,
I read this and loved it. +1.
People, good commit messages and comments are essential for code
maintenance. Let's make everyone's life easier by:
1) Being thoughtful writing the messages
2) Proofreading
3) Spell checking
Thanks!
Lucas
Several maintainers have noted lately a decrease in commit & comment
quality. I promised I'd write up a quick reminder/guide for everyone in
response. This is non-specific/general advice, and we understand this
"English" thing isn't everyone's first language - Point in fact,
sometimes even *I* question if it's a language at all, or just a random
collection of random rules that randomly make sense randomly :) Good
commits and comments are very much more of an art than a science.
Anyway, I hope this helps...
-----------------------------------------------------------------------
Comments: Write "why" not "what" you are doing. If it was easy to write
a comment, you probably did it wrong :) Instead, pretend you're new to
the code or section, seeing it for the first time ever. You can read
the small code/section, and understand the language. However, what is
not in the language is _why_ it is there instead of somewhere else, and
how does it relate to the code around it.
Example Code:
Z = X + Y
Bad comment (explains "what"):
# Add two numbers together to find the answer.
Good comment (explains "why"):
# When X or Y change, other value can be derived for comparison.
After reading the "bad" example, you have no more information that you
can get by just reading the code. However, with the "good" example, you
can practically imagine what code comes next and why calculating Z
before it is important. Also, bugs will more clearly stand out, since
the following code won't match what the comment says the prior code is
for. It's OKAY to spend a lot more time writing a comment, then writing
the code itself!
-----------------------------------------------------------------------
Commit messages: These are critical for someone else understand (maybe
years later), what the situation was and the overall context surrounding
the changes. Pretend the diff or code becomes lost or corrupted, and
someone unfamiliar must recreate all your work from only the
description, using as few words as possible. Similar to comments, this
is much more about writing "why" and not "what".
The summary line (the first line of the commit message) is arguably the
most important and the most constrained (50 to 78 characters MAX!) For
the autotest & virt-test project, it should begin with the primary
sub-section name or github label associated with the changes (e.g.
autotest, virt (general), virt-qemu (specific), spice, etc.). That
means you have an even smaller space to summarize, maybe 40-60 characters!
Bad commit:
Changed foobar.py to have more comments and look nice.
Changed 5 lines in /path/to/foobar.py
Grand super project master leader said my function was too
slow and ugly so I delete it. I did not eat breakfast this morning.
Good commit:
useful-utilities: Prepare for new plugin API in next release.
Original author left many complex formulas unexplained. The
fromanite() function is planned to be replaced with new
additions. It does not meet current performance demand
for 3 eggs and 2 bacon before 9am.
The bad example does not provide any information that can't be found by
just reading the diff. To understand these changes, someone else might
have to go searching through years old mailing list messages and chat
logs. The good example explains what was happening at the time (i.e.
the context) and offers specific details into why the changes are
needed. Accidental typos or changes in unrelated code will clearly
stand out, since that part of the diff won't match the commit message
descriptions.
Tip: I often find it easier to write the summary line _after_ I write
the rest of the commit message. When I find it hard to summarize, that
usually means the commit should be split - Use the super handy, dandy
command 'git add --patch --edit <filename>' to split it up file by file
interactively!
For further reading, I found this old-ish blog post helpful:
http://who-t.blogspot.de/2009/12/on-commit-messages.html
_______________________________________________
Virt-test-devel mailing list
[email protected]
https://www.redhat.com/mailman/listinfo/virt-test-devel
