On 04/18/2017 04:24 PM, Ehsan Akhgari wrote:
On 2017-04-18 12:30 AM, Mike Hommey wrote:
I've yet to see that to happen. What is crucial is fast way to browse
through the blame in time. So commit messages should be short and
descriptive. Telling what and why. (I very often need to go back to CVS era
code). I won't spend time reading several paragraphs of commit messages.
Those are just too long.
Basically first line should tell the essentials 'what' and maybe the most
obvious 'why' and the next couple of lines explaining 'why' more precisely.
Don't write stories which will make blame-browsing slower.
What sort of blame-browsing makes more than the first line of the commit
message a burden? I'm curious, because that doesn't match my use of
blame.
I can't say I have had this issue, and I also do a lot of code
archaeology as well. I suppose to a large extent this does depend on
what tools you use, perhaps. These days I use searchfox.org for a lot
of blame browsing that I do, which displays only the first line in the
default UI and only displays the full commit message when you look at
the full commit. I find this a pretty good balance.
And I've done my share of archeology and for old enough stuff you often
end up with one of:
- a completely useless commit message *and* useless bug (if there's even
a bug number)
- a mostly useless commit message and some information in the bug.
You're lucky if it's all contained in a few sentences.
- a mostly useless commit message and tons of information in the bug,
that you have to spend quite some time parsing through.
In *all* cases, you have to go switch between your blame and bugzilla.
It's a PITA. Now, when you have everything in VCS, you just work with
your blame. Obviously, CVS-era commits are not going to change, but do
you really want to keep things in the same state for commits done now,
when you (or someone else) goes through blame in a few years?
Agreed.
Also even for newer code you often end up in the third category. Maybe
it's just me but I spend a lot of time reading old bugs, and I find it a
huge time sink to read through tons of comments just to find where the
actual discussion about why the fix was done in the way that it was done
happened in the bug. Sometimes I have to really read 100+ comments.
And the sad reality is that all too often I find very questionable
things in patches happen in bugs without any discussion whatsoever which
means that sometimes one can spend half an hour reading those 100+
comments very carefully to find out in the end that they have just
wasted their time and the bug actually did not contain the interesting
information in the first place.
I think I would probably sympathize more with the side of the argument
arguing for bugs as the source of the truth if this wasn't really true,
but I think part of the reason why people don't bother writing good
commit messages is that they assume that the reasons behind the
approaches they take and the design decisions and the like are obvious,
and while that may be true *now* and to them and the code reviewer, it
will not be true to everyone and in the future, and because of that if
you're not careful the important information is just not captured
anywhere. I hope we can all agree that it's important that we capture
this information for the maintainability of our code, even if we can't
agree where the information needs to be captured. :-)
The important part of documentation should be in code comments, not commit
messages.
We aren't too good commenting code.
Another thing, today I was looking at a bug which has several patches, and realized one can't really understand the big picture by looking at commit
messages of some particular commit. There needs to be some centralized place for that, and it is the bug. Going through each patches individually and
looking at the commit messages would be really painful way to see what and why was changed.
_______________________________________________
dev-platform mailing list
dev-platform@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-platform
