You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by "Kathey Marsden (JIRA)" <de...@db.apache.org> on 2006/08/04 01:47:18 UTC
[jira] Commented: (DERBY-1363) Derby should publish a well defined
coding convention per the db project guidlines
[ http://issues.apache.org/jira/browse/DERBY-1363?page=comments#action_12425637 ]
Kathey Marsden commented on DERBY-1363:
---------------------------------------
Putting handling of existing code aside, I would like to propose we adopt the client code format moving forward. My reasons have nothing to do with love of that actual format but are as follows:
1) We need a coding convention to be in compliance with the db project guidlines.
2) A large portion of the code is already in that format, Jeremy made a pass after contribution.
3) This issue has wasted huge amounts of time for the Derby community and burnt virtually every new developer.
4) The format if as Jeremy described should be fairly easy to configure in most IDE's.
Here is Jeremy's description of that format.
http://www.nabble.com/Re%3A-Reformat-client-code--p9229.html
It needs to be researched and documented and perhaps items that are already on the checklist like 80 characters per line added.
Jeremy sure was right about the bikeshed discussion [1] and very wise to just pull the band-aid off quick despite all the whining by me and others. Please before you consider raising serious objections to this consider all it has and will cost the project if we don't come to consensus on this.
If there are no objections, we can then take the next step to document the format and next figure out how to get there for the full code base, but if we can get past this step I think we will have made great progress on this issue.
Kathey
http://www.unixguide.net/freebsd/faq/16.19.shtml
> Derby should publish a well defined coding convention per the db project guidlines
> ----------------------------------------------------------------------------------
>
> Key: DERBY-1363
> URL: http://issues.apache.org/jira/browse/DERBY-1363
> Project: Derby
> Issue Type: Task
> Components: Web Site
> Reporter: Kathey Marsden
> Fix For: 10.2.0.0
>
>
> The DB project guidlines dictate that we should have a well defined convention for coding standards.
> http://db.apache.org/source.html says
> "Java Language source code in the repository must be written in conformance to the " Code Conventions for the Java Programming Language as published by Sun, or in conformance with another well-defined convention specified by the subproject. See the FAQ page for links to subproject conventions."
> We should publish at least a well defined convention for new code in order to comply with the db project guidlines.
> Discussion for whether to reformat or not once that is decided is under discussion in the thread:
> http://www.nabble.com/Code+formatting+debate%2C+confusion+and+wasted+time+%2C+Has+it+gone+on+long+enough--t1710825.html
> but at least the coding standards should be defined.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
Re: [jira] Commented: (DERBY-1363) Derby should publish a well defined
coding convention per the db project guidlines
Posted by Daniel John Debrunner <dj...@apache.org>.
Kathey Marsden wrote:
> Daniel John Debrunner wrote:
>
>> -1 to defining a new format, why not just pick some existing standard.
>>
>> +1 to defining some format.
>>
>>
>>
> I will try just a little longer and then we can just all go back to our
> pain.
> We go with the way the client code is described but drop the mandatory
> braces around blocks so the client code should still fit.
>
> <proposal>
> Sun default style with 4 space indent (no tabs).
> </proposal>
I looked at this & I now understand why it's not just the Sun style. The
Sun style contains this "The exact construction of the indentation
(spaces vs. tabs) is unspecified. Tabs must be set exactly every 8
spaces (not 4).", so I assume the addition is to specify the indentation.
Of course there's one section of the Sun standard I dislike and think
works against the power of the Java language, possibly leading to bugs,
but to raise it would be a bikeshed discussion. :-)
Dan.
Re: [jira] Commented: (DERBY-1363) Derby should publish a well defined
coding convention per the db project guidlines
Posted by David Van Couvering <Da...@Sun.COM>.
I agree, we need to be careful about global reformatting; I think the
biggest issue is around tabs vs. spaces. If svn diff can ignore white
space in diffs, that would be great, and we could go ahead and convert
(carefully) all the code.
I also wouldn't even mind a filter running on svn commit that converts
all tabs to spaces, if it can be accomplished safely.
David
Mike Matrigali wrote:
> I still don't think it is worth it to reformat all the code style, but
> do think addressing the tab/space issue is worth it. Before we do any
> reformatting I would like to clearly understand the process and any
> likelyhood that the automated reformatter will introduce bugs into the
> code.
>
> My main problem is the future nightmare of backporting code. This
> change will definitely increase the cost/time/likelyhood of backporting
> changes. For instance most of the store code bracket style is
> consistent but different than the sun style. I know eol changes caused
> merges that should have been automatic to turn into hours worth of
> work for me in the past.
>
> I understand the tab/space issue and think that changing to all spaces
> would help and my hope is that with appropriate flags to patch/svn we
> could get merges to ignore space diffs.
>
>
> Kathey Marsden wrote:
>> Daniel John Debrunner wrote:
>>
>>> -1 to defining a new format, why not just pick some existing standard.
>>>
>>> +1 to defining some format.
>>>
>>>
>>>
>> I will try just a little longer and then we can just all go back to
>> our pain.
>> We go with the way the client code is described but drop the
>> mandatory braces around blocks so the client code should still fit.
>>
>> <proposal>
>> Sun default style with 4 space indent (no tabs).
>> </proposal>
>>
>> The Sun default is what is recommended at:
>> http://db.apache.org/source.html
>>
>>
>> Kathey
>>
>>
>>
>
Re: Upcoming code convention vote
Posted by Yip Ng <yi...@gmail.com>.
I think this is fine. Once this coding convention is finalized, the wiki
page http://wiki.apache.org/db-derby/DerbyContributorChecklist should be
updated.
Yip
On 8/10/06, Bryan Pendleton <bp...@amberpoint.com> wrote:
>
> > I think that we should probably have a formal vote now
>
> This seems fine to me.
>
> I suggest reformatting the main paragraph to make it slightly more
> explicit
> that we are adopting these conventions incorporating these amendments. So
> I am suggesting something like this:
>
> Derby uses the "Code Conventions for the Java Programming Language"
> (http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html) with these
> amendments:
> - space indentation (no tabs).
> - Derby does not discourage deferring variable declaration to the first
> use.
> - Lines should be limited to 80 characters
> - @author tags should not be used at all
>
> Note: There is a great deal of existing code that does not match this
> convention. Changes to existing code should match the surrounding code
> for readability, matching tabs or spaces as appropriate (see Tabs) .
> Patches should not have white space diffs. Code and diffs should be
> readable in context.
>
>
> thanks,
>
> bryan
>
>
Re: Upcoming code convention vote
Posted by Bryan Pendleton <bp...@amberpoint.com>.
> I think that we should probably have a formal vote now
This seems fine to me.
I suggest reformatting the main paragraph to make it slightly more explicit
that we are adopting these conventions incorporating these amendments. So
I am suggesting something like this:
Derby uses the "Code Conventions for the Java Programming Language"
(http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html) with these
amendments:
- space indentation (no tabs).
- Derby does not discourage deferring variable declaration to the first use.
- Lines should be limited to 80 characters
- @author tags should not be used at all
Note: There is a great deal of existing code that does not match this
convention. Changes to existing code should match the surrounding code
for readability, matching tabs or spaces as appropriate (see Tabs) .
Patches should not have white space diffs. Code and diffs should be
readable in context.
thanks,
bryan
Re: Upcoming code convention vote (was Re: [jira] Commented: (DERBY-1363)
Derby should publish a well defined coding convention per the db project
guidlines)
Posted by Kathey Marsden <km...@sbcglobal.net>.
Suresh Thalamati wrote:
>
> Is it really necessary to use TABS on an existing code files with the
> tabs. I am wondering if it would be ok to use 4/8 spaces instead to
> match the surrounding code.
>
Most folks set their editors to have 4 space tabs , so if you use a 4
space tab it looks ok, but if you cat the file or look at a visual
diff the tabs are 8. So, we end up with patches like the one I just
looked at, DERBY-1456 where the indentation is off when you diff the
files. If you used 8 spaces instead of a tab, of course things would be
ok for the cat or the diff, but off for the folks that set their tabs to
4. The procedure outlined in the Tabs section of the
ContributorChecklist[1] I think will work to make sure that code looks
ok in both contexts.
The mixed tab/space mess is what Francois calls an "infection" and I
agree. My hope is that after the convention is approved, we can go on
to talk about an ultimate resolution for that problem . I think this
means reformatting the code on all the branches and removing the Note in
the convention, but that is a fodder for a subsequent discussion and
*not* part of this vote, just a bit of hope I have for the future.
Kathey
[1] http://wiki.apache.org/db-derby/DerbyContributorChecklist
Re: Upcoming code convention vote (was Re: [jira] Commented: (DERBY-1363)
Derby should publish a well defined coding convention per the db project
guidlines)
Posted by Suresh Thalamati <su...@gmail.com>.
Kathey Marsden wrote:
> Kathey Marsden wrote:
>
<snip ..>
> Note: There is a great deal of existing code that does not match this
> convention. Changes to existing code should match the surrounding code
> for readability, matching tabs or spaces as appropriate (see Tabs) .
Is it really necessary to use TABS on an existing code files with the
tabs. I am wondering if it would be ok to use 4/8 spaces instead to
match the surrounding code.
Thanks
-suresh
Upcoming code convention vote (was Re: [jira] Commented: (DERBY-1363)
Derby should publish a well defined coding convention per the db project
guidlines)
Posted by Kathey Marsden <km...@sbcglobal.net>.
Kathey Marsden wrote:
> Do we need a formal vote?
I think that we should probably have a formal vote now on the wording
and at least get formal +1 votes from a few committers. If later there
are changes to the code that make the note about the existing code not
necessary, then that code change can go through the normal code
submission channels and that wording removed without controversy or vote
I think. The vote text will look like this:
Subject : [VOTE] Approve coding conventions for the Derby project
This is a vote to define the coding conventions for the Derby project
per the db project guidelines http://db.apache.org/source.html
Derby uses the "Code Conventions for the Java Programming Language"
(http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html) with space
indentation (no tabs). One variation is that Derby does not discourage
deferring variable declaration to the first use. Lines should be
limited to 80 characters and @author tags should not be used at all.
Note: There is a great deal of existing code that does not match this
convention. Changes to existing code should match the surrounding code
for readability, matching tabs or spaces as appropriate (see Tabs) .
Patches should not have white space diffs. Code and diffs should be
readable in context.
[+1] Adopt the coding convention described.
[-1 ] Do not adopt the coding convention described.
Any objections to the content or wording that need further discussion?
Any objections to starting a vote tomorrow morning and closing Tuesday
4pm PST?
I'll post for vote tomorrow if I don't hear anything.
Kathey
Re: [jira] Commented: (DERBY-1363) Derby should publish a well defined
coding convention per the db project guidlines
Posted by Kathey Marsden <km...@sbcglobal.net>.
Kathey Marsden wrote:
>
> Dan, what is your quality concern with the Sun convention and how
> might we best mitigate it?
>
I talked with Dan briefly about this yesterday. His concern was that
section 6.3 indicates that declaration placement should be at the
beginning of block. It says: "Don't wait to declare variables until
their first use." The concern is that this convention forces
artificial expansion of scope which can be dangerous, especially if
initialization, included with the declaration is for primitives. Knut
also pointed out recently that it does not make the code clearer [1].
I think that we can safely amend our convention to exclude this part of
the convention for 2 reasons.
1) I agree it is a legitimate quality risk and we have enough of those.
2) I think there is no way, even if there was agreement that the
beginning of the block was good and all could agree that reformatting
was good, that our existing code would ever be adjusted.
So here is my suggested wording for the DerbyContributorChecklist [2] for
Coding Convention (changed from "Coding standard" to make it sound less
militant)
Derby uses the "Code Conventions for the Java Programming Language" [3]
with space indentation (no tabs). One variation is that Derby does not
discourage deferring variable declaration to the first use. Lines
should be limited to 80 characters and @author tags should not be used
at all. Note: There is a great deal of existing code that does not
match this convention. Changes to existing code should match the
surrounding code for readability, matching tabs or spaces as appropriate
(see Tabs) . Patches should not have white space diffs. Code and diffs
should be readable in context.
Any strong objections to this shed color or ideas for improved
wording? Do we need a formal vote?
Kathey
[1] Knut's comments :
https://issues.apache.org/jira/browse/DERBY-1320#action_12423783
[2] DerbyContributorChecklist :
http://wiki.apache.org/db-derby/DerbyContributorChecklist
[3] Code Conventions for the Java Programming Language :
http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
Re: [jira] Commented: (DERBY-1363) Derby should publish a well defined
coding convention per the db project guidlines
Posted by Kathey Marsden <km...@sbcglobal.net>.
Kathey Marsden wrote:
I think we are converging on deciding on a color for our shed:
>
>
> Code Conventions for the Java Programming Language
> <http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html> as
> published by Sun [1] with four space indent (no tabs)
>
Included in this convention is the 80 character line limit and
implicit in our participation at a Apache is the lack of @author tags,
but I think these items should be included in the final wording. This
approach feels generally OK to me because this is the standard
indicated in the db project guidelines, and it is the base for the
Geronimo and Jakarta standards. My only concern is that Dan said there
was an inherent quality risk in the Sun standard and I am not willing to
introduce a known quality risk without understanding it. I think we
can surely mitigate whatever it is with cautionary wording or slight
amendment, but need to have all the data on the table. Aesthetic
opinions should be avoided to prevent a bikeshed discussion, quality
data points should not.
Dan, what is your quality concern with the Sun convention and how might
we best mitigate it?
Kathey
Re: [jira] Commented: (DERBY-1363) Derby should publish a well defined
coding convention per the db project guidlines
Posted by Kathey Marsden <km...@sbcglobal.net>.
Mike Matrigali wrote:
> I still don't think it is worth it to reformat all the code style, but
> do think addressing the tab/space issue is worth it.
My hope is to address this incrementally. My only goal right now is to
do define a long term coding style for the project and for new code.
I'd rather not include repainting the shed in the discussion right now,
just deciding on a color. I am not proposing code reformatting at this
time.
After this current effort , the contributor checklist might say the
following about Coding Standards and Tabs
Coding Standards
The Derby community will use the [ snip decided standard] moving
forward. New code should conform to this standard. However, there is a
great deal of existing code that does not match this standard. Changes
to existing code should match the surrounding code for readability,
matching tabs or spaces as appropriate (see Tabs)
Tabs
Most of the existing code that has tabs expect tab-width to be set to 4
spaces. This was the original Cloudscape convention. With this
setting your code should look readable. When editing existing code
with tabs, use tabs and set your tab-width to 4. After editing, set
tabs back to 8 or view with a simple text editor to make sure the code
indentation is consistent.
Right now the proposed [snip decided standard] is
Code Conventions for the Java Programming Language
<http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html> as
published by Sun [1] with four space indent (no tabs)
Any objections? Once we fill in [snip decided standard] with something
that can get through without veto we can try to make additional progress
on the issue. Having a long term destination is an important first
step, even if our path will still be filled with tripwires. Right now
we are tripping in every direction. After deciding the base color for
our shed long term we can discuss optional trim and the impact of
actually repainting is worth it.
Thanks
Kathey
[1] http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
Re: [jira] Commented: (DERBY-1363) Derby should publish a well defined
coding convention per the db project guidlines
Posted by Mike Matrigali <mi...@sbcglobal.net>.
I still don't think it is worth it to reformat all the code style, but
do think addressing the tab/space issue is worth it. Before we do any
reformatting I would like to clearly understand the process and any
likelyhood that the automated reformatter will introduce bugs into the
code.
My main problem is the future nightmare of backporting code. This
change will definitely increase the cost/time/likelyhood of backporting
changes. For instance most of the store code bracket style is
consistent but different than the sun style. I know eol changes caused
merges that should have been automatic to turn into hours worth of
work for me in the past.
I understand the tab/space issue and think that changing to all spaces
would help and my hope is that with appropriate flags to patch/svn we
could get merges to ignore space diffs.
Kathey Marsden wrote:
> Daniel John Debrunner wrote:
>
>> -1 to defining a new format, why not just pick some existing standard.
>>
>> +1 to defining some format.
>>
>>
>>
> I will try just a little longer and then we can just all go back to our
> pain.
> We go with the way the client code is described but drop the mandatory
> braces around blocks so the client code should still fit.
>
> <proposal>
> Sun default style with 4 space indent (no tabs).
> </proposal>
>
> The Sun default is what is recommended at:
> http://db.apache.org/source.html
>
>
> Kathey
>
>
>
Re: [jira] Commented: (DERBY-1363) Derby should publish a well defined
coding convention per the db project guidlines
Posted by Kathey Marsden <km...@sbcglobal.net>.
Daniel John Debrunner wrote:
>-1 to defining a new format, why not just pick some existing standard.
>
>+1 to defining some format.
>
>
>
I will try just a little longer and then we can just all go back to our
pain.
We go with the way the client code is described but drop the mandatory
braces around blocks so the client code should still fit.
<proposal>
Sun default style with 4 space indent (no tabs).
</proposal>
The Sun default is what is recommended at:
http://db.apache.org/source.html
Kathey
Re: [jira] Commented: (DERBY-1363) Derby should publish a well defined
coding convention per the db project guidlines
Posted by Daniel John Debrunner <dj...@apache.org>.
Dag H. Wanvik wrote:
> "Kathey Marsden (JIRA)" <de...@db.apache.org> writes:
>
>
>> [ http://issues.apache.org/jira/browse/DERBY-1363?page=comments#action_12425637 ]
>>
>>Kathey Marsden commented on DERBY-1363:
>>---------------------------------------
>>
>>Putting handling of existing code aside, I would like to propose we
>>adopt the client code format moving forward. My reasons have
>>nothing to do with love of that actual format but are as follows:
>
>
> +1, anything to get rid of the current mess.
-1 to defining a new format, why not just pick some existing standard.
+1 to defining some format.
Dan.
Re: [jira] Commented: (DERBY-1363) Derby should publish a well defined
coding convention per the db project guidlines
Posted by "Dag H. Wanvik" <Da...@Sun.COM>.
"Kathey Marsden (JIRA)" <de...@db.apache.org> writes:
> [ http://issues.apache.org/jira/browse/DERBY-1363?page=comments#action_12425637 ]
>
> Kathey Marsden commented on DERBY-1363:
> ---------------------------------------
>
> Putting handling of existing code aside, I would like to propose we
> adopt the client code format moving forward. My reasons have
> nothing to do with love of that actual format but are as follows:
+1, anything to get rid of the current mess.
Dag
>
> 1) We need a coding convention to be in compliance with the db
> project guidlines.
> 2) A large portion of the code is already in that format, Jeremy
> made a pass after contribution.
> 3) This issue has wasted huge amounts of time for the Derby
> community and burnt virtually every new developer.
> 4) The format if as Jeremy described should be fairly easy to
> configure in most IDE's.
>
> Here is Jeremy's description of that format.
> http://www.nabble.com/Re%3A-Reformat-client-code--p9229.html
> It needs to be researched and documented and perhaps items that are
> already on the checklist like 80 characters per line added.
>
> Jeremy sure was right about the bikeshed discussion [1] and very
> wise to just pull the band-aid off quick despite all the whining by
> me and others. Please before you consider raising serious
> objections to this consider all it has and will cost the project if
> we don't come to consensus on this.
>
> If there are no objections, we can then take the next step to
> document the format and next figure out how to get there for the
> full code base, but if we can get past this step I think we will
> have made great progress on this issue.