You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tuscany.apache.org by ant elder <an...@gmail.com> on 2009/06/01 18:15:41 UTC
Re: Commit comment quality?
On Fri, May 29, 2009 at 5:36 PM, Simon Laws <si...@googlemail.com> wrote:
> I've noticed over the last couple of months that we have, on some
> occasions, become a little lax about adding the "why" alongside the
> "what" in our commit comments. Particularly problematic when there is
> no JIRA to refer to. I'm as much a culprit as anyone else so I'm not
> throwing rocks here but it would be useful to me if, as we're
> reviewing each others changes, we can call out when we think the
> comment isn't sufficient or clear enough so that the justification can
> be updated and it becomes a matter of record. I seems that there are
> some innovative discussions firing up on 2.x and it would be good to
> be able to help people follow the twists and turns as best we can.
>
> Is this a fair observation?
>
> Simon
>
+1. Commit comments saying why not what with as much detail as is
necessary to help others understand the change remembering that
there's lots of room so more than one sentence is ok if required. Also
several small discrete commits are easier to understand than one
commit which has several different changes. Also try to do formatting
changes separately because it can be real hard to see whats changed if
formatting is mixed with other code changes. And another type i find a
bit irksome is comments that only mention a JIRA number eg "Fix
TUSCANY-xxxx" but not what the JIRA is about so you have to go look it
up yourself.
...ant
Re: Commit comment quality?
Posted by Raymond Feng <en...@gmail.com>.
Same here. I prefer to use JIRA to track the details.
Thanks,
Raymond
--------------------------------------------------
From: "Simon Nash" <na...@apache.org>
Sent: Tuesday, June 02, 2009 7:17 AM
To: <de...@tuscany.apache.org>
Subject: Re: Commit comment quality?
> ant elder wrote:
>> On Fri, May 29, 2009 at 5:36 PM, Simon Laws <si...@googlemail.com>
>> wrote:
>>> I've noticed over the last couple of months that we have, on some
>>> occasions, become a little lax about adding the "why" alongside the
>>> "what" in our commit comments. Particularly problematic when there is
>>> no JIRA to refer to. I'm as much a culprit as anyone else so I'm not
>>> throwing rocks here but it would be useful to me if, as we're
>>> reviewing each others changes, we can call out when we think the
>>> comment isn't sufficient or clear enough so that the justification can
>>> be updated and it becomes a matter of record. I seems that there are
>>> some innovative discussions firing up on 2.x and it would be good to
>>> be able to help people follow the twists and turns as best we can.
>>>
>>> Is this a fair observation?
>>>
>>> Simon
>>>
>>
>> +1. Commit comments saying why not what with as much detail as is
>> necessary to help others understand the change remembering that
>> there's lots of room so more than one sentence is ok if required. Also
>> several small discrete commits are easier to understand than one
>> commit which has several different changes. Also try to do formatting
>> changes separately because it can be real hard to see whats changed if
>> formatting is mixed with other code changes. And another type i find a
>> bit irksome is comments that only mention a JIRA number eg "Fix
>> TUSCANY-xxxx" but not what the JIRA is about so you have to go look it
>> up yourself.
>>
>> ...ant
>>
> I have often used the "Fix TUSCANY-xxx" style of commmit comment,
> together with a longer comment in the JIRA explaining the change.
> IMO this is better than putting the long explanation in the commit
> comment, because it makes it easier for people to find the
> explanation later. I don't find it inconvenient to look in a
> JIRA to get this information.
>
> For commits without a JIRA, I agree that a longer explanatory
> commit comment is desirable.
>
> Simon
>
>
Re: Commit comment quality?
Posted by Luciano Resende <lu...@gmail.com>.
On Tue, Jun 2, 2009 at 7:39 AM, ant elder <an...@gmail.com> wrote:
> On Tue, Jun 2, 2009 at 3:17 PM, Simon Nash <na...@apache.org> wrote:
>
>> I have often used the "Fix TUSCANY-xxx" style of commmit comment,
>> together with a longer comment in the JIRA explaining the change.
>> IMO this is better than putting the long explanation in the commit
>> comment, because it makes it easier for people to find the
>> explanation later.
>
> IMHO its much better to have a more than just the JIRA number in the
> commit log. Doesn't have to be a long explanation, having "Fix
> TUSCANY-xxx," followed by the one line heading from the JIRA is what I
> do and that doesn't seem particularly onerous but gives enough to
> easily get an idea of what the commit is for.
>
+1, I'd prefer to have the JIRA ID + some short info about the details
of the fix.... any further information could be later retrieved from
the JIRA.
--
Luciano Resende
Apache Tuscany, Apache PhotArk
http://people.apache.org/~lresende
http://lresende.blogspot.com/
Re: Commit comment quality?
Posted by ant elder <an...@gmail.com>.
On Tue, Jun 2, 2009 at 3:17 PM, Simon Nash <na...@apache.org> wrote:
> I have often used the "Fix TUSCANY-xxx" style of commmit comment,
> together with a longer comment in the JIRA explaining the change.
> IMO this is better than putting the long explanation in the commit
> comment, because it makes it easier for people to find the
> explanation later.
IMHO its much better to have a more than just the JIRA number in the
commit log. Doesn't have to be a long explanation, having "Fix
TUSCANY-xxx," followed by the one line heading from the JIRA is what I
do and that doesn't seem particularly onerous but gives enough to
easily get an idea of what the commit is for.
...ant
Re: Commit comment quality?
Posted by Simon Nash <na...@apache.org>.
ant elder wrote:
> On Fri, May 29, 2009 at 5:36 PM, Simon Laws <si...@googlemail.com> wrote:
>> I've noticed over the last couple of months that we have, on some
>> occasions, become a little lax about adding the "why" alongside the
>> "what" in our commit comments. Particularly problematic when there is
>> no JIRA to refer to. I'm as much a culprit as anyone else so I'm not
>> throwing rocks here but it would be useful to me if, as we're
>> reviewing each others changes, we can call out when we think the
>> comment isn't sufficient or clear enough so that the justification can
>> be updated and it becomes a matter of record. I seems that there are
>> some innovative discussions firing up on 2.x and it would be good to
>> be able to help people follow the twists and turns as best we can.
>>
>> Is this a fair observation?
>>
>> Simon
>>
>
> +1. Commit comments saying why not what with as much detail as is
> necessary to help others understand the change remembering that
> there's lots of room so more than one sentence is ok if required. Also
> several small discrete commits are easier to understand than one
> commit which has several different changes. Also try to do formatting
> changes separately because it can be real hard to see whats changed if
> formatting is mixed with other code changes. And another type i find a
> bit irksome is comments that only mention a JIRA number eg "Fix
> TUSCANY-xxxx" but not what the JIRA is about so you have to go look it
> up yourself.
>
> ...ant
>
I have often used the "Fix TUSCANY-xxx" style of commmit comment,
together with a longer comment in the JIRA explaining the change.
IMO this is better than putting the long explanation in the commit
comment, because it makes it easier for people to find the
explanation later. I don't find it inconvenient to look in a
JIRA to get this information.
For commits without a JIRA, I agree that a longer explanatory
commit comment is desirable.
Simon
Re: Commit comment quality?
Posted by Vamsavardhana Reddy <c1...@gmail.com>.
+1 to not mix formatting and code changes in a single commit.
On Wed, Jun 24, 2009 at 12:06 PM, ant elder <an...@gmail.com> wrote:
>
>
> On Mon, Jun 1, 2009 at 5:15 PM, ant elder <an...@gmail.com> wrote:
>
>
>> Also try to do formatting
>> changes separately because it can be real hard to see whats changed if
>> formatting is mixed with other code changes.
>
>
> Does anyone disagree that commits should not mix formatting and code
> changes?
>
> ...ant
>
--
Vamsi
Re: Commit comment quality?
Posted by Simon Laws <si...@googlemail.com>.
On Wed, Jun 24, 2009 at 7:36 AM, ant elder<an...@gmail.com> wrote:
>
>
> On Mon, Jun 1, 2009 at 5:15 PM, ant elder <an...@gmail.com> wrote:
>
>>
>> Also try to do formatting
>> changes separately because it can be real hard to see whats changed if
>> formatting is mixed with other code changes.
>
> Does anyone disagree that commits should not mix formatting and code
> changes?
>
> ...ant
>
+1
Simon
Re: Commit comment quality?
Posted by Luciano Resende <lu...@gmail.com>.
On Wed, Jun 24, 2009 at 6:45 AM, Simon Laws<si...@googlemail.com> wrote:
> On Wed, Jun 24, 2009 at 2:27 PM, Luciano Resende<lu...@gmail.com> wrote:
>> On Tue, Jun 23, 2009 at 11:36 PM, ant elder<an...@gmail.com> wrote:
>>>
>>> Does anyone disagree that commits should not mix formatting and code
>>> changes?
>>>
>>
>> There are some settings on the Eclipse templates we use that do some
>> conversion automatically (e.g tabs for spaces)... are those accepted
>> ? What makes things hard to see, is the CTRL+F to reformat or CTRL+I
>> to reident the code when fixing a bug, and for that I'd prefer to use
>> a separate commit.
>>
>>
>>
>> --
>> Luciano Resende
>> Apache Tuscany, Apache PhotArk
>> http://people.apache.org/~lresende
>> http://lresende.blogspot.com/
>>
>
> Yeah, for me that's the issue. If we go in and fix a bug and
> automatically reformat the whole source file at the same time and
> commit then that makes it hard to spot the line that's actually
> changed to fix a problem. Obviously if it's just reformatting around
> the change to fit the change in that that's part of the change itself.
> I'm talking about reformatting that is independent of the change.
>
> If large scale/automatic reformatting could be done separately from
> changes to the logic then that would make life easier.
>
> Regards
>
> Simon
>
Then, +1
--
Luciano Resende
Apache Tuscany, Apache PhotArk
http://people.apache.org/~lresende
http://lresende.blogspot.com/
Re: Commit comment quality?
Posted by Simon Laws <si...@googlemail.com>.
On Wed, Jun 24, 2009 at 2:27 PM, Luciano Resende<lu...@gmail.com> wrote:
> On Tue, Jun 23, 2009 at 11:36 PM, ant elder<an...@gmail.com> wrote:
>>
>> Does anyone disagree that commits should not mix formatting and code
>> changes?
>>
>
> There are some settings on the Eclipse templates we use that do some
> conversion automatically (e.g tabs for spaces)... are those accepted
> ? What makes things hard to see, is the CTRL+F to reformat or CTRL+I
> to reident the code when fixing a bug, and for that I'd prefer to use
> a separate commit.
>
>
>
> --
> Luciano Resende
> Apache Tuscany, Apache PhotArk
> http://people.apache.org/~lresende
> http://lresende.blogspot.com/
>
Yeah, for me that's the issue. If we go in and fix a bug and
automatically reformat the whole source file at the same time and
commit then that makes it hard to spot the line that's actually
changed to fix a problem. Obviously if it's just reformatting around
the change to fit the change in that that's part of the change itself.
I'm talking about reformatting that is independent of the change.
If large scale/automatic reformatting could be done separately from
changes to the logic then that would make life easier.
Regards
Simon
Re: Commit comment quality?
Posted by ant elder <an...@apache.org>.
On Wed, Jun 24, 2009 at 5:07 PM, Raymond Feng <en...@gmail.com> wrote:
> Hi,
>
> We have an agreed Eclipse template, why can't people have the code
> formatting done using the code style in the 1st place?
>
The code style/format has come up several times over the years, there never
has been complete agreement, the eclipse template we have checked in to svn
doesn't even match the idea one we also have checked in. From what I recall
the last time formatting was discussed the general consensus was mainly
things like: when you're updating code try to match the format its already
in, don't use excessively long lines, and don't use tabs.
I think we have to be a little tolerant of formatting, even if absolutely
everyone uses the eclipse template its easy for it to get dropped off and
not noticed when someone gets a new machine, or does a new IDE install.
> I agree not to reformat the whole file at the same time when we fix the
> code, but I don't think we go too far. I have a few things set up
> automatically in Eclipse:
>
> * Organize the imports
Organise imports is fine IMHO as its a small number of lines all at the very
top thats easy to skip over as we don't need to think about the changes too
much.
> * Convert the tab/space
>
I'd _really_ prefer you not do this automatically as it really does make it
harder to see what you're doing. When tabs/spaces is wrong in a file its
often wrong on lots of lines so a commit for even just a small change can
end up with quite a big diff of several screens full which we need to scroll
full hunting for the actual changes.
>
> It helps me a lot to maintain the clean code with disturbing the diffs too
> much.
>
If we do the thing you suggest next then i don't think the not doing
tabs/spaces conversion automatically will be such a problem for you as most
of the files will be fine as they get fixed up regularly.
>
> The other thing, can we reformat the whole code base before we cut a RC so
> that we can have good style moving forward?
>
For the tabs/spaces conversion and organize imports, yes lets, thats a good
idea. I'd happy to do this when I'm RM for a release if we can find an easy
way to do it, and actually doesn't even need to be just for a release, we
could run a tabs/spaces conversion and organize imports across the entire
trunk when ever anyone gets the urge to do it or someone notices a few files
have gone wrong.
I'm less keen on a complete format as the eclipse formatter just doesn't
seem that good IMHO so things like comments don't get auto formatted
particularly well.
>
> Thanks,
> Raymond
> --------------------------------------------------
> From: "ant elder" <an...@apache.org>
> Sent: Wednesday, June 24, 2009 7:02 AM
> To: <de...@tuscany.apache.org>
> Subject: Re: Commit comment quality?
>
> On Wed, Jun 24, 2009 at 2:27 PM, Luciano Resende<lu...@gmail.com>
>> wrote:
>>
>>> On Tue, Jun 23, 2009 at 11:36 PM, ant elder<an...@gmail.com> wrote:
>>>
>>>>
>>>> Does anyone disagree that commits should not mix formatting and code
>>>> changes?
>>>>
>>>>
>>> There are some settings on the Eclipse templates we use that do some
>>> conversion automatically (e.g tabs for spaces)... are those accepted
>>> ?
>>>
>>
>> I'd don't think those should be done automatically and from other
>> projects its standard practice to to keep those separate in another
>> commit. We're all busy so reviewing changes should be able to be done
>> as quick and easily as possible, so ideally just read the comment and
>> a quick flick over the diff, if that diff includes many other lines of
>> change even just for tab/space changes it makes it harder than
>> necessary to see the actual code lines changed.
>>
>> ...ant
>>
>
>
Re: Commit comment quality?
Posted by Luciano Resende <lu...@gmail.com>.
On Thu, Jun 25, 2009 at 7:39 AM, Simon Nash<na...@apache.org> wrote:
> Luciano Resende wrote:
>>
>> On Wed, Jun 24, 2009 at 9:07 AM, Raymond Feng<en...@gmail.com> wrote:
>>>
>>> Hi,
>>>
>>> We have an agreed Eclipse template, why can't people have the code
>>> formatting done using the code style in the 1st place?
>>>
>>
>> +1, Although this is not mandatory, I'd really like to encourage the
>> Tuscany developers (at least the core ones) to be using the templates
>> as we describe in our developer guide. If there are issues with the
>> current template, let' s discuss it and fix it.
>>
> I prefer to use a plain text editor. I am careful to follow the
> guidelines on tabs/spaces, long lines, and import ordering.
> I don't mix reformatting with other changes. I don't think it
> should be a requirement to use any particular editor.
>
> Simon
>
This is fine Simon, at least the text editor won't be reformatting
anything automatically.
--
Luciano Resende
Apache Tuscany, Apache PhotArk
http://people.apache.org/~lresende
http://lresende.blogspot.com/
Re: Commit comment quality?
Posted by Simon Nash <na...@apache.org>.
Luciano Resende wrote:
> On Wed, Jun 24, 2009 at 9:07 AM, Raymond Feng<en...@gmail.com> wrote:
>> Hi,
>>
>> We have an agreed Eclipse template, why can't people have the code
>> formatting done using the code style in the 1st place?
>>
>
> +1, Although this is not mandatory, I'd really like to encourage the
> Tuscany developers (at least the core ones) to be using the templates
> as we describe in our developer guide. If there are issues with the
> current template, let' s discuss it and fix it.
>
I prefer to use a plain text editor. I am careful to follow the
guidelines on tabs/spaces, long lines, and import ordering.
I don't mix reformatting with other changes. I don't think it
should be a requirement to use any particular editor.
Simon
>> I agree not to reformat the whole file at the same time when we fix the
>> code, but I don't think we go too far. I have a few things set up
>> automatically in Eclipse:
>>
>> * Organize the imports
>
> +1
>
>> * Convert the tab/space
>>
>
> +1
>
>> It helps me a lot to maintain the clean code with disturbing the diffs too
>> much.
>>
>
> +1
>
>> The other thing, can we reformat the whole code base before we cut a RC so
>> that we can have good style moving forward?
>>
>
> We could do this frequently, I tried the import/export in the whole
> codebase and it seems to be very straightforward and I'll commit if I
> don't see any build issues.
>
>
>> Thanks,
>> Raymond
>> --------------------------------------------------
>> From: "ant elder" <an...@apache.org>
>> Sent: Wednesday, June 24, 2009 7:02 AM
>> To: <de...@tuscany.apache.org>
>> Subject: Re: Commit comment quality?
>>
>>> On Wed, Jun 24, 2009 at 2:27 PM, Luciano Resende<lu...@gmail.com>
>>> wrote:
>>>> On Tue, Jun 23, 2009 at 11:36 PM, ant elder<an...@gmail.com> wrote:
>>>>> Does anyone disagree that commits should not mix formatting and code
>>>>> changes?
>>>>>
>>>> There are some settings on the Eclipse templates we use that do some
>>>> conversion automatically (e.g tabs for spaces)... are those accepted
>>>> ?
>>> I'd don't think those should be done automatically and from other
>>> projects its standard practice to to keep those separate in another
>>> commit. We're all busy so reviewing changes should be able to be done
>>> as quick and easily as possible, so ideally just read the comment and
>>> a quick flick over the diff, if that diff includes many other lines of
>>> change even just for tab/space changes it makes it harder than
>>> necessary to see the actual code lines changed.
>>>
>>> ...ant
>>
>
>
>
Re: Commit comment quality?
Posted by Luciano Resende <lu...@gmail.com>.
On Wed, Jun 24, 2009 at 9:07 AM, Raymond Feng<en...@gmail.com> wrote:
> Hi,
>
> We have an agreed Eclipse template, why can't people have the code
> formatting done using the code style in the 1st place?
>
+1, Although this is not mandatory, I'd really like to encourage the
Tuscany developers (at least the core ones) to be using the templates
as we describe in our developer guide. If there are issues with the
current template, let' s discuss it and fix it.
> I agree not to reformat the whole file at the same time when we fix the
> code, but I don't think we go too far. I have a few things set up
> automatically in Eclipse:
>
> * Organize the imports
+1
> * Convert the tab/space
>
+1
> It helps me a lot to maintain the clean code with disturbing the diffs too
> much.
>
+1
> The other thing, can we reformat the whole code base before we cut a RC so
> that we can have good style moving forward?
>
We could do this frequently, I tried the import/export in the whole
codebase and it seems to be very straightforward and I'll commit if I
don't see any build issues.
> Thanks,
> Raymond
> --------------------------------------------------
> From: "ant elder" <an...@apache.org>
> Sent: Wednesday, June 24, 2009 7:02 AM
> To: <de...@tuscany.apache.org>
> Subject: Re: Commit comment quality?
>
>> On Wed, Jun 24, 2009 at 2:27 PM, Luciano Resende<lu...@gmail.com>
>> wrote:
>>>
>>> On Tue, Jun 23, 2009 at 11:36 PM, ant elder<an...@gmail.com> wrote:
>>>>
>>>> Does anyone disagree that commits should not mix formatting and code
>>>> changes?
>>>>
>>>
>>> There are some settings on the Eclipse templates we use that do some
>>> conversion automatically (e.g tabs for spaces)... are those accepted
>>> ?
>>
>> I'd don't think those should be done automatically and from other
>> projects its standard practice to to keep those separate in another
>> commit. We're all busy so reviewing changes should be able to be done
>> as quick and easily as possible, so ideally just read the comment and
>> a quick flick over the diff, if that diff includes many other lines of
>> change even just for tab/space changes it makes it harder than
>> necessary to see the actual code lines changed.
>>
>> ...ant
>
>
--
Luciano Resende
Apache Tuscany, Apache PhotArk
http://people.apache.org/~lresende
http://lresende.blogspot.com/
Re: Commit comment quality?
Posted by Raymond Feng <en...@gmail.com>.
Hi,
We have an agreed Eclipse template, why can't people have the code
formatting done using the code style in the 1st place?
I agree not to reformat the whole file at the same time when we fix the
code, but I don't think we go too far. I have a few things set up
automatically in Eclipse:
* Organize the imports
* Convert the tab/space
It helps me a lot to maintain the clean code with disturbing the diffs too
much.
The other thing, can we reformat the whole code base before we cut a RC so
that we can have good style moving forward?
Thanks,
Raymond
--------------------------------------------------
From: "ant elder" <an...@apache.org>
Sent: Wednesday, June 24, 2009 7:02 AM
To: <de...@tuscany.apache.org>
Subject: Re: Commit comment quality?
> On Wed, Jun 24, 2009 at 2:27 PM, Luciano Resende<lu...@gmail.com>
> wrote:
>> On Tue, Jun 23, 2009 at 11:36 PM, ant elder<an...@gmail.com> wrote:
>>>
>>> Does anyone disagree that commits should not mix formatting and code
>>> changes?
>>>
>>
>> There are some settings on the Eclipse templates we use that do some
>> conversion automatically (e.g tabs for spaces)... are those accepted
>> ?
>
> I'd don't think those should be done automatically and from other
> projects its standard practice to to keep those separate in another
> commit. We're all busy so reviewing changes should be able to be done
> as quick and easily as possible, so ideally just read the comment and
> a quick flick over the diff, if that diff includes many other lines of
> change even just for tab/space changes it makes it harder than
> necessary to see the actual code lines changed.
>
> ...ant
Re: Commit comment quality?
Posted by ant elder <an...@apache.org>.
On Wed, Jun 24, 2009 at 2:27 PM, Luciano Resende<lu...@gmail.com> wrote:
> On Tue, Jun 23, 2009 at 11:36 PM, ant elder<an...@gmail.com> wrote:
>>
>> Does anyone disagree that commits should not mix formatting and code
>> changes?
>>
>
> There are some settings on the Eclipse templates we use that do some
> conversion automatically (e.g tabs for spaces)... are those accepted
> ?
I'd don't think those should be done automatically and from other
projects its standard practice to to keep those separate in another
commit. We're all busy so reviewing changes should be able to be done
as quick and easily as possible, so ideally just read the comment and
a quick flick over the diff, if that diff includes many other lines of
change even just for tab/space changes it makes it harder than
necessary to see the actual code lines changed.
...ant
Re: Commit comment quality?
Posted by Luciano Resende <lu...@gmail.com>.
On Tue, Jun 23, 2009 at 11:36 PM, ant elder<an...@gmail.com> wrote:
>
> Does anyone disagree that commits should not mix formatting and code
> changes?
>
There are some settings on the Eclipse templates we use that do some
conversion automatically (e.g tabs for spaces)... are those accepted
? What makes things hard to see, is the CTRL+F to reformat or CTRL+I
to reident the code when fixing a bug, and for that I'd prefer to use
a separate commit.
--
Luciano Resende
Apache Tuscany, Apache PhotArk
http://people.apache.org/~lresende
http://lresende.blogspot.com/
Re: Commit comment quality?
Posted by ant elder <an...@gmail.com>.
On Mon, Jun 1, 2009 at 5:15 PM, ant elder <an...@gmail.com> wrote:
> Also try to do formatting
> changes separately because it can be real hard to see whats changed if
> formatting is mixed with other code changes.
Does anyone disagree that commits should not mix formatting and code
changes?
...ant