Re: Please don't use revision numbers on commit messages (and elsewhere).

[Uday S Reddy <u.s.reddy@cs.bham.ac.uk>]

Óscar Fuentes writes:

> I see that as a tradeoff writer vs readers. As explained elsewhere, you
> write things once but they are read lots of times. It is the same case
> as naming functions and writing comments.

That is of course a very good point.  Revision notes should be easy
enough to read, but *analyzing* them might involve some work.  In
practice, it involves a lot of work, and one addition/subtraction
isn't going to make much of a difference.

Going back to your original example, which is presumably fictitious:

> If I'm reading the VC log on a random branch and see "Fix breakage
> introduced by rXXXX" and want to look at the referenced revision,
> ...

the problem with such a note is that it says precious little unless
you go and find the revision XXXX.  Those of us that write technical
articles have been taught to use the convention that the text should
stand on its own without having to follow the cross-references to
understand what it is saying.  (I have been told that it is what is
recommended by the Chicago Manual of Style, though I haven't read the
manual myself.)  Your example fails that test.  If there is enough
information in the note for the reader to decide whether it is
necessary to follow the cross-reference, then readability would be
preserved.

The various real examples cited by Juanma seem to be mostly fine.

Cheers,
Uday