Re: [PATCH 7/8] CodingGuidelines: on comparison

From: Junio C Hamano <gitster@pobox.com>
Date: May 2, 2014, 18:18 UTC
Message-ID: <xmqqk3a4avt1.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20140501213657.GC14441@sigill.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 8 quoted lines

> On Wed, Apr 30, 2014 at 02:45:11PM -0700, Junio C Hamano wrote:
>
>> See http://thread.gmane.org/gmane.comp.version-control.git/3903/focus=4126
>> 
>> Signed-off-by: Junio C Hamano <gitster@pobox.com>
>
> Don't you often complain about submitters referencing a discussion
> in a commit message without providing some context or summary?

Yes, but the summary of the discussion would be identical to the new text added by the patch to the documentation tree in this case, so I didn't find a good introductory text before "See $URL". Perhaps

    This comes up from time to time.  See $URL for the original
    discussion.

but I do not know if that is much better.

Show 19 quoted lines

>> + - There are two schools of thought when it comes to comparison,
>> +   especially inside a loop. Some people prefer to have less stable
>> +   value on the left hand side and more stable value on the right hand
>> +   side, e.g. if you have a loop that counts variable i down to the
>> +   lower bound,
>
> Grammar: /(less|more) stable/the &/
>
>> +   Both are valid, and we use both, even though we tend to see the
>> +   former the more preferable, the more "stable" the more stable side
>> +   becomes (comparison with a constant, "i > 0", is an extreme
>> +   example).  Just do not mix styles in the same part of the code.
>> +
>
> I had trouble parsing the first sentence. Maybe:
>
>   Both are valid, and we use both. However, the more "stable" the stable
>   side becomes, the more we tend to prefer the former (comparison with a
>   constant[...]

Thanks.  That is much better.