develooper Front page | perl.perl5.porters | Postings from December 2009

Re: [fwd] [perl.git] branch blead, updated. v5.11.3-15-gbdaf0bc (from: jesse@bestpractical.com)

Thread Previous | Thread Next
From:
demerphq
Date:
December 31, 2009 02:50
Subject:
Re: [fwd] [perl.git] branch blead, updated. v5.11.3-15-gbdaf0bc (from: jesse@bestpractical.com)
Message ID:
9b18b3110912310249r5ebd7a3cm67105eb78c696b51@mail.gmail.com
2009/12/31 demerphq <demerphq@gmail.com>:
> 2009/12/31 Abigail <abigail@abigail.be>:
>> On Wed, Dec 30, 2009 at 03:58:16PM -0500, jesse wrote:
>>> Karl Williamson pointed out to me that we were recommending single-line
>>> commit messages as "the right way to do things" in perlrepository.pod.
>>>
>>> I've taken a first stab at fleshing out some suggestions and guidelines
>>> about commit messages.  It could use more work. Patches would be
>>> appreciated.
>>>
>>> --
>>
>> The first time I read it, it was giving me the impression to put in the
>> commit message what you'd put in a code comment.
>>
>> Perhaps we should add a line saying that a commit message in no way replaces
>> code comments.
>
> Ill just stick up my hand and say I dont really agree in practice but
> that I agree with the sentiment.

Just to explain, a one line or small patch may actually need several
paragraphs of explanation. Putting those paragraphs in the code can
lead to code that is so obfuscated by comments that it is
unmaintainable. A small comment indicating that a fuller explanation
is in the commit message to me seems like a good balance.

The larger the patch the more reasonable it is that it includes
internal commentary independent of the commit message, and that
correspondingly that commit messages for large patches can be less
explanatory than small ones.

A large patch adding multiple functions, tests and etc, is essentially
self documenting and might justify a commit message like "Add new
regex logic for char classes", whereas a oneliner commit almost
always, typo fixes aside, deserves at least a paragraph why it is
being changed.

My opinion only btw. Im not trying to say this should be policy or anything.

Cheers,
Yves





-- 
perl -Mre=debug -e "/just|another|perl|hacker/"

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About