You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tuscany.apache.org by Simon Laws <si...@googlemail.com> on 2009/05/29 18:36:08 UTC
Commit comment quality?
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
Re: Commit comment quality?
Posted by Simon Laws <si...@googlemail.com>.
>
> It looks like we all understand what each other issues and preferences
> are by now. How about we watch the behavior in the commit
> notifications for the next two or three weeks and see if we all make
> improvements...
>
>
> --
> Luciano Resende
> Apache Tuscany, Apache PhotArk
> http://people.apache.org/~lresende
> http://lresende.blogspot.com/
>
+1 Luciano.
Re: Commit comment quality?
Posted by Luciano Resende <lu...@gmail.com>.
On Fri, Jun 5, 2009 at 12:18 AM, ant elder <an...@gmail.com> wrote:
> On Thu, Jun 4, 2009 at 2:34 PM, Simon Laws<si...@googlemail.com> wrote:
>> ...snip
>>
>>> It would be much more burdensome
>>> to do multiple commits so that a tailored comment can be used for each
>>> separate change.
>>
>> I'm not for a moment suggesting that the number of commits made should
>> be dictated by the commit comments.
>>
>
> I am ;) Well ok not "dictate" but it should be a consideration.
>
> Apache projects and Commit-Then-Review only work when others know and
> understand whats going on, easy to grok commits helps get that group
> understanding. If a change is hard to understand people don't bother
> trying, so we miss out on that initial review that may catch some
> bugs, but also as others start getting out of touch they are less
> likely to help maintain that bit of code which results in bugs not
> getting fixed promptly, mailing lists questions going unanswered,
> documentation not getting updated etc. In the extreme eventually
> circumstance will require that that bit of function must be updated
> but as others don't really understand it instead of improving the
> existing code it gets ripped out and rewritten. Thats a very
> inefficient way to develop the project and also will likely make the
> original coder less likely to continue contributing.
>
> Of course there are no hard rules on this and it depends on the change
> and the preferences and style of the person making the change but IMHO
> it is worth for the greater good spending a little extra time to try
> and see if a big change can be broken up into several smaller easy to
> understand commits.
>
> ...ant
>
It looks like we all understand what each other issues and preferences
are by now. How about we watch the behavior in the commit
notifications for the next two or three weeks and see if we all make
improvements...
--
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 Thu, Jun 4, 2009 at 2:34 PM, Simon Laws<si...@googlemail.com> wrote:
> ...snip
>
>> It would be much more burdensome
>> to do multiple commits so that a tailored comment can be used for each
>> separate change.
>
> I'm not for a moment suggesting that the number of commits made should
> be dictated by the commit comments.
>
I am ;) Well ok not "dictate" but it should be a consideration.
Apache projects and Commit-Then-Review only work when others know and
understand whats going on, easy to grok commits helps get that group
understanding. If a change is hard to understand people don't bother
trying, so we miss out on that initial review that may catch some
bugs, but also as others start getting out of touch they are less
likely to help maintain that bit of code which results in bugs not
getting fixed promptly, mailing lists questions going unanswered,
documentation not getting updated etc. In the extreme eventually
circumstance will require that that bit of function must be updated
but as others don't really understand it instead of improving the
existing code it gets ripped out and rewritten. Thats a very
inefficient way to develop the project and also will likely make the
original coder less likely to continue contributing.
Of course there are no hard rules on this and it depends on the change
and the preferences and style of the person making the change but IMHO
it is worth for the greater good spending a little extra time to try
and see if a big change can be broken up into several smaller easy to
understand commits.
...ant
Re: Commit comment quality?
Posted by Simon Laws <si...@googlemail.com>.
...snip
> It would be much more burdensome
> to do multiple commits so that a tailored comment can be used for each
> separate change.
I'm not for a moment suggesting that the number of commits made should
be dictated by the commit comments.
..snip
Simon
Re: Commit comment quality?
Posted by Simon Nash <na...@apache.org>.
Simon Laws wrote:
> I find
>
> "Fix TUSCANY-xxx"
>
> Less satisfactory than
>
> TUSCANY-xxx change abc because ...
> or
> change abc because ...
>
> For two reasons.
>
> 1/ I often look at the log of changes for a given file or a group if
> files. This shows a list of changes and having to de-reference to the
> JIRA is a pain when you are trying to get an overview of the ebb and
> flow of changes in a particular area. This is particularly the case
> when you are reading down a long list trying to find the particular
> change that is contributing to whatever problem you are currently
> working on. I think of it like reading the "CHANGES" file we create
> for a release as a whole. I find having just JIRA numbers there is
> also less that satisfactory.
>
> 2/ A JIRA often has many changes associated with it and tying down the
> reason for one particular change, even within the context of a single
> JIRA, is not always easy
>
When I fix a JIRA, I usually do a single commit for all the changes.
This will have a single commit comment. It would be much more burdensome
to do multiple commits so that a tailored comment can be used for each
separate change. If a more detailed breakdown of the changes for a
complex fix is needed, I think the best place for this is the JIRA.
> We may get to the point where it's a question of taste. It doesn't
> seem to me to be a great burden to put a sentence of explanation in at
> the point at which a change is committed, the point at which the
> change is fresh in the committers mind, to help those of us who find
> it useful regardless of whether the committer is going to use it in
> the future
>
In the case described above with many changes to fix a single JIRA,
it would be very difficult to come up with a one-sentence summary
that's more helpful than "Fixed TUSCANY-xxxx". It would be possible
to add a bit more information about the JIRA problem (e.g., "incorrect
WSDL generated"). For more than that, I think the JIRA is the right
place.
Simon
> I am not proposing that for 2.x we have a JIRA for ever change. It is
> attractive for 1.x though where the changes are becoming more about
> maintenance and less about new development.
>
> Simon
>
>
Re: Commit comment quality?
Posted by Simon Laws <si...@googlemail.com>.
I find
"Fix TUSCANY-xxx"
Less satisfactory than
TUSCANY-xxx change abc because ...
or
change abc because ...
For two reasons.
1/ I often look at the log of changes for a given file or a group if
files. This shows a list of changes and having to de-reference to the
JIRA is a pain when you are trying to get an overview of the ebb and
flow of changes in a particular area. This is particularly the case
when you are reading down a long list trying to find the particular
change that is contributing to whatever problem you are currently
working on. I think of it like reading the "CHANGES" file we create
for a release as a whole. I find having just JIRA numbers there is
also less that satisfactory.
2/ A JIRA often has many changes associated with it and tying down the
reason for one particular change, even within the context of a single
JIRA, is not always easy
We may get to the point where it's a question of taste. It doesn't
seem to me to be a great burden to put a sentence of explanation in at
the point at which a change is committed, the point at which the
change is fresh in the committers mind, to help those of us who find
it useful regardless of whether the committer is going to use it in
the future
I am not proposing that for 2.x we have a JIRA for ever change. It is
attractive for 1.x though where the changes are becoming more about
maintenance and less about new development.
Simon
Re: Commit comment quality?
Posted by Ramkumar R <ra...@gmail.com>.
>
> Creating a jira for each single commit will flood the dev list with
> unnecessary jira notifications (create, close, etc) and will probably
> make users that are lurking in the dev list to unsubscribe... It
> should be pretty simple to just add a simple description on the commit
> log message, and associate it with a jira if one exists. This makes
> life easy for the ones just looking into the commit e-mails from last
> night, or the ones looking into some tool like TortoiseSVN, but also
> simple for people browsing jira, as the commit tab will easily display
> the list of revisions that were changed in relation to this specific
> jira.
>
Agree with Simon and Luciano's point of view. +1
--
Thanks & Regards,
Ramkumar Ramalingam
Re: Commit comment quality?
Posted by Simon Laws <si...@googlemail.com>.
> Creating a jira for each single commit will flood the dev list with
> unnecessary jira notifications (create, close, etc) and will probably
> make users that are lurking in the dev list to unsubscribe... It
> should be pretty simple to just add a simple description on the commit
> log message, and associate it with a jira if one exists. This makes
> life easy for the ones just looking into the commit e-mails from last
> night, or the ones looking into some tool like TortoiseSVN, but also
> simple for people browsing jira, as the commit tab will easily display
> the list of revisions that were changed in relation to this specific
> jira.
+1
Re: Commit comment quality?
Posted by Luciano Resende <lu...@gmail.com>.
On Wed, Jun 3, 2009 at 8:16 AM, Mike Edwards
<mi...@gmail.com> wrote:
> I have to admit to NOT raising a JIRA for "trivial" changes - instead I try
> to put the explanation into the Commit message.
>
+1
> The sort of change that I regard as too trivial for a JIRA are upgrades to
> error messages which are not changing any significant logic in the code.
>
> If people feel a need for a JIRA for everything, then I'll consider
> changing, but I'd prefer to keep the burden low for doing minor incremental
> improvements of this kind.
>
Creating a jira for each single commit will flood the dev list with
unnecessary jira notifications (create, close, etc) and will probably
make users that are lurking in the dev list to unsubscribe... It
should be pretty simple to just add a simple description on the commit
log message, and associate it with a jira if one exists. This makes
life easy for the ones just looking into the commit e-mails from last
night, or the ones looking into some tool like TortoiseSVN, but also
simple for people browsing jira, as the commit tab will easily display
the list of revisions that were changed in relation to this specific
jira.
--
Luciano Resende
Apache Tuscany, Apache PhotArk
http://people.apache.org/~lresende
http://lresende.blogspot.com/
Re: Commit comment quality?
Posted by Mike Edwards <mi...@gmail.com>.
Ramkumar R wrote:
> Hi Simon,
>
> Agree with you, I am one such culprit for recently checking in codes for
> spring module
> refactoring without a JIRA. I realized the mistake later when I had to
> track the changes
> that were made for the entire spring refactoring work.
>
> My suggestion is that, we should always have a JIRA associated for any
> code changes
> going forward and follow the "Fix TUSCANY-xxx" style of commmit comment.
>
> --
> Thanks & Regards,
> Ramkumar Ramalingam
Folks,
I have to admit to NOT raising a JIRA for "trivial" changes - instead I try to put the explanation
into the Commit message.
The sort of change that I regard as too trivial for a JIRA are upgrades to error messages which are
not changing any significant logic in the code.
If people feel a need for a JIRA for everything, then I'll consider changing, but I'd prefer to keep
the burden low for doing minor incremental improvements of this kind.
Yours, Mike.
Re: Commit comment quality?
Posted by Ramkumar R <ra...@gmail.com>.
Hi Simon,
Agree with you, I am one such culprit for recently checking in codes for
spring module
refactoring without a JIRA. I realized the mistake later when I had to track
the changes
that were made for the entire spring refactoring work.
My suggestion is that, we should always have a JIRA associated for any code
changes
going forward and follow the "Fix TUSCANY-xxx" style of commmit comment.
On Fri, May 29, 2009 at 10:06 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
>
--
Thanks & Regards,
Ramkumar Ramalingam
Re: Commit comment quality?
Posted by Luciano Resende <lu...@gmail.com>.
On Fri, May 29, 2009 at 9:53 AM, kelvin goodson <ke...@gmail.com> wrote:
> The "why" associated with a commit is so very valuable to anyone
> trying to get to grips with a project's source code.
>
> 2009/5/29 Simon Laws <si...@googlemail.com>:
>> 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?
>>
+1
On my side, I noticed that sometimes GIT is overriding some commit
messages with "merge <branch name>", and I'll look on how to fix this
issue.
--
Luciano Resende
Apache Tuscany, Apache PhotArk
http://people.apache.org/~lresende
http://lresende.blogspot.com/
Re: Commit comment quality?
Posted by kelvin goodson <ke...@gmail.com>.
The "why" associated with a commit is so very valuable to anyone
trying to get to grips with a project's source code.
2009/5/29 Simon Laws <si...@googlemail.com>:
> 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
>
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
Re: Commit comment quality?
Posted by ant elder <an...@gmail.com>.
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