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 <km...@sbcglobal.net> on 2006/08/12 01:53:03 UTC
[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
Vote closes 10:00am, Wednesday, August 15.
[+1] Adopt the coding convention described.
[-1 ] Do not adopt the coding convention described.
The conventions outlined below will be published on the wiki page
http://wiki.apache.org/db-derby/DerbyContributorChecklist
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.
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Kathey Marsden <km...@sbcglobal.net>.
Kathey Marsden wrote:
Correction:
> Vote closes 10:00am, Wednesday, August *16*.
>
And my vote:
> [+1] Adopt the coding convention described.
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Kathey Marsden <km...@sbcglobal.net>.
Daniel John Debrunner wrote:
>timezone?
>
>
>
If we need a timezone, we can go by my watch which would be:
Vote closes 10:00am PST, Wednesday, August 16.
I usually just loiter to post the results, past the designated time
anywhere in the world #:)
Kathey
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Daniel John Debrunner <dj...@apache.org>.
Kathey Marsden wrote:
> This is a vote to define the coding conventions for the Derby project
> per the db project guidelines http://db.apache.org/source.html
> Vote closes 10:00am, Wednesday, August 15.
timezone?
Dan.
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Bryan Pendleton <bp...@amberpoint.com>.
> This is a vote to define the coding conventions for the Derby project
My vote is:
> [+1] Adopt the coding convention described.
thanks,
bryan
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Knut Anders Hatlen <Kn...@Sun.COM>.
Kathey Marsden <km...@sbcglobal.net> writes:
> This is a vote to define the coding conventions for the Derby project
> per the db project guidelines http://db.apache.org/source.html
> Vote closes 10:00am, Wednesday, August 15.
>
> [+1] Adopt the coding convention described.
> [-1 ] Do not adopt the coding convention described.
[+1] Adopt the coding convention described.
--
Knut Anders
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Andreas Korneliussen <An...@Sun.COM>.
+1 Adopt the coding convention described.
Andreas
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Kristian Waagan <Kr...@Sun.COM>.
Kathey Marsden wrote:
> This is a vote to define the coding conventions for the Derby project
> per the db project guidelines http://db.apache.org/source.html
> Vote closes 10:00am, Wednesday, August 15.
>
My vote:
> [+1] Adopt the coding convention described.
--
Kristian
>
> The conventions outlined below will be published on the wiki page
> http://wiki.apache.org/db-derby/DerbyContributorChecklist
>
> 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.
>
>
>
Re: [VOTE] Approve coding conventions for the Derby project
Posted by "Dag H. Wanvik" <Da...@Sun.COM>.
Kathey Marsden <km...@sbcglobal.net> writes:
> BTW: I would most appreciate a pointer to a diff uitlity where I can
> set tab stops to 4 if anyone knows of one.
svn diff | expand -t 4
should work.
Dag
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Kathey Marsden <km...@sbcglobal.net>.
Suresh Thalamati wrote:
>
> I find it hard to switch between spaces for new files and tabs for old
> files. It is pain to remember to find, if a file is
> tab-formatted/space-formatted, and format appropriately.
>
> If most of the current code is formatted with tabs, why not use tabs
> until we decided to reformat the code with spaces.
>
>
Unfortunately, this does not work as a large portion of the code (the
complete set of client code and other code as well ) already has
space indentation. Indenting with tabs and setting tab stop 4 in your
editor causes diff utilities such as svn diff and the visual diff tool
that I use to have unreadable indentation and making reviews very
hard. Again using 4 space indentation in tab indented code creates
the same problem with diffs.
We are gradually moving from driving on the left side of the road to the
right which is painful.
Kathey
BTW: I would most appreciate a pointer to a diff uitlity where I can set
tab stops to 4 if anyone knows of one.
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Suresh Thalamati <su...@gmail.com>.
Kathey Marsden wrote:
> This is a vote to define the coding conventions for the Derby project
> per the db project guidelines http://db.apache.org/source.html
> Vote closes 10:00am, Wednesday, August 15.
>
> [+1] Adopt the coding convention described.
> [-1 ] Do not adopt the coding convention described.
>
> The conventions outlined below will be published on the wiki page
> http://wiki.apache.org/db-derby/DerbyContributorChecklist
My vote is : -0.25
I find it hard to switch between spaces for new files and tabs for old
files. It is pain to remember to find, if a file is
tab-formatted/space-formatted, and format appropriately.
If most of the current code is formatted with tabs, why not use tabs
until we decided to reformat the code with spaces.
Thank
-suersh
Re: [VOTE] Approve coding conventions for the Derby project
Posted by "Dag H. Wanvik" <Da...@Sun.COM>.
[+1] Adopt the coding convention described.
I think the incremental strategy is good here; it helps break the
impasse. Thanks, Kathey!
Dag
Re: [VOTE] Approve coding conventions for the Derby project
Posted by "Bernt M. Johnsen" <Be...@Sun.COM>.
I think I'm counted twice: +1 from "Bernt M. Johnsen" and -0 from
"Bernt Johnson". Not that it matters ver much, but I actually voted -0.
> Kathey Marsden wrote:
> Below are the results from this vote:
>
> [+1] Adopt the coding convention described.
>
> David Van Couvering (Committer)
> Bryan Pendleton (Committer)
> Craig Russell
> Kristian Waagan
> Knut Anders Hatlen (Committer)
> Narayan
> Dag Wanvik
> Andreas Korneliussen (Committer)
> Kathey Marsden (Committer)
> Bernt M. Johnsen (Committer)
> Olav Sandstaa
>
>
> -0 Rick Hilegas (Committer)
> Mike Matrigali (Committer)
> Bernt Johnson (Committer)
>
>
> -.25
> Suresh Thalmamati. (Committer)
>
> Did the vote pass? I am not totally sure, but I think so. Did we reach
> consensus? I don't think so.
> I think such a vote should be pure formality and all necessary
> discussion and refinement should happen before hand. Clearly there was
> more discussion needed and I think the discussion in the course of this
> vote was some of the most productive we have had on the topic. If I
> could go back in time and add the amendment:
>
> - Derby encourages writing of clear code and use of common sense and
> does not discourage variations from the convention that lead to better
> code clarity and do not interfere with the general use of the
> convention by others in the project.
>
> Some general comments from the discussion. I hope I got this right.
> Please respond with corrections additions.
>
> In general
> As things stand, we could better document the tab stop 4. clear code
> and no formatting/white space diffs in patches to mitigate our current
> problems.
>
> On the postive side:
> - Most folks thought the amendments and note were good.
> - Clarity on our long term direction for tab/spaces and convention
> will help us develop an action plan to address those issues.
> Positive comments on having a fairly specific convention.
> - Having a fairly specific convention that contributors and
> editor stetting that contributors can use safely without extended
> discussion will save the project lots of time and potential confusion.
> - Having braces etc all the same leads to better overall code
> clarity.
> On the negative side:
> - The wording was too strong about the convention to use and made it
> sound mandatory and might interfere with common sense and clarity of code .
> - Ultimate reformatting to the convention would cause ":merge hell"
> (I don't think this is true if we reformat all the branches)
> - Folks wanted to get the space/tab issue and problem of
> reformatting in patches resolved more independently from any long term
> convention. (I am concerned that this might lead to the need to
> reformat twice if other issues arise).
> - Wanted a better statement of the problems we are trying to solve
> before solutions were presented.
> - Did not like having to adapt to tabs or spaces of the surrounding
> code. Wanted a clear setting of tabs or spaces which would be ok. (I
> don't think we can do this given the current state)
> - Code conventions for the sake of db project guideline compliance is
> not a good motivation.
>
> I am not exactly sure how to proceed moving forward. The incremental
> consensus approach is good I think, but perhaps this step was to big
> and too prescriptive for the next step of resolving inconsistencies in
> the code (especially tab/spaces).
>
> I think I will detach from this for a bit and not update anything on the
> contributor checklist. If someone wants to pick it up and glean some
> areas of clear consensus from it that can go on the checklist or wants
> to take other action, please do. This thread is here for historical
> context for all and especially for whomever wants to continue. I might
> look at it again later after witnessing the next hazing ritual if no one
> else has.
>
> Kathey
>
--
Bernt Marius Johnsen, Database Technology Group,
Staff Engineer, Technical Lead Derby/Java DB
Sun Microsystems, Trondheim, Norway
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Kathey Marsden <km...@sbcglobal.net>.
Kathey Marsden wrote:
Below are the results from this vote:
[+1] Adopt the coding convention described.
David Van Couvering (Committer)
Bryan Pendleton (Committer)
Craig Russell
Kristian Waagan
Knut Anders Hatlen (Committer)
Narayan
Dag Wanvik
Andreas Korneliussen (Committer)
Kathey Marsden (Committer)
Bernt M. Johnsen (Committer)
Olav Sandstaa
-0
Rick Hilegas (Committer)
Mike Matrigali (Committer)
Bernt Johnson (Committer)
-.25
Suresh Thalmamati. (Committer)
Did the vote pass? I am not totally sure, but I think so.
Did we reach consensus? I don't think so.
I think such a vote should be pure formality and all necessary
discussion and refinement should happen before hand. Clearly there was
more discussion needed and I think the discussion in the course of this
vote was some of the most productive we have had on the topic. If I
could go back in time and add the amendment:
- Derby encourages writing of clear code and use of common sense and
does not discourage variations from the convention that lead to better
code clarity and do not interfere with the general use of the
convention by others in the project.
Some general comments from the discussion. I hope I got this right.
Please respond with corrections additions.
In general
As things stand, we could better document the tab stop 4. clear code
and no formatting/white space diffs in patches to mitigate our current
problems.
On the postive side:
- Most folks thought the amendments and note were good.
- Clarity on our long term direction for tab/spaces and convention
will help us develop an action plan to address those issues.
Positive comments on having a fairly specific convention.
- Having a fairly specific convention that contributors and
editor stetting that contributors can use safely without extended
discussion will save the project lots of time and potential confusion.
- Having braces etc all the same leads to better overall code
clarity.
On the negative side:
- The wording was too strong about the convention to use and made
it sound mandatory and might interfere with common sense and clarity of
code .
- Ultimate reformatting to the convention would cause ":merge
hell" (I don't think this is true if we reformat all the branches)
- Folks wanted to get the space/tab issue and problem of
reformatting in patches resolved more independently from any long term
convention. (I am concerned that this might lead to the need to
reformat twice if other issues arise).
- Wanted a better statement of the problems we are trying to solve
before solutions were presented.
- Did not like having to adapt to tabs or spaces of the surrounding
code. Wanted a clear setting of tabs or spaces which would be ok. (I
don't think we can do this given the current state)
- Code conventions for the sake of db project guideline compliance is
not a good motivation.
I am not exactly sure how to proceed moving forward. The incremental
consensus approach is good I think, but perhaps this step was to big
and too prescriptive for the next step of resolving inconsistencies in
the code (especially tab/spaces).
I think I will detach from this for a bit and not update anything on
the contributor checklist. If someone wants to pick it up and glean
some areas of clear consensus from it that can go on the checklist or
wants to take other action, please do. This thread is here for
historical context for all and especially for whomever wants to
continue. I might look at it again later after witnessing the next
hazing ritual if no one else has.
Kathey
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Kathey Marsden <km...@sbcglobal.net>.
Rick Hillegas wrote:
> We can amend our conventions later on. Again, I don't want to bring
> this vote to a halt. I am changing my vote to
>
> -0
>
Thanks Rick. I appreciate your willingness to defer revisions to
another round. I think there were great potential improvements that
came out of this conversation and vote. I especially like Bernt's
suggestion that we add an amendment to "- use common sense " and move
the statement about no whitespace or reformatting diffs in patches up to
the ammendments. Hopefully this type of change will be a much easier
sell and can happen without a big formal vote.
Thanks again for your patience.
Kathey
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Rick Hillegas <Ri...@Sun.COM>.
Kathey Marsden wrote:
> Rick Hillegas wrote:
>
>>
>> I'm not sure I understand this point. If we recommend a style primer,
>> then I think we're saying that the style is safe and we don't expect
>> committers to flunk a conforming patch for style reasons--provided,
>> of course, that the code is clear. "Recommended" means "safe". I'm
>> just saying it doesn't mean "mandatory". I don't think our
>> perspectives are that far apart.
>>
> I don't think I as a new developer would read the primer pointer as
> being safe, nor as an existing developer would I read in this the
> need to make sure that new developers could use that convention safely.
> I would like to better understand whether your objection to the
> proposed wording. Is it that it will inhibit your personal style
> choices or is it that you are concerned that others in the future
> might interpret it to mean their style choices are limited and that is
> bad for the project in some way?
>
> Kathey
>
I think that there are sound reasons to depart from this style depending
on the particular problem your code is solving. Some have been
discussed. Others will come up. I am content to deal with them on a
case-by-case basis. We can amend our conventions later on. Again, I
don't want to bring this vote to a halt. I am changing my vote to
-0
Regards,
-Rick
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Kathey Marsden <km...@sbcglobal.net>.
Rick Hillegas wrote:
>
> I'm not sure I understand this point. If we recommend a style primer,
> then I think we're saying that the style is safe and we don't expect
> committers to flunk a conforming patch for style reasons--provided, of
> course, that the code is clear. "Recommended" means "safe". I'm just
> saying it doesn't mean "mandatory". I don't think our perspectives are
> that far apart.
>
I don't think I as a new developer would read the primer pointer as
being safe, nor as an existing developer would I read in this the need
to make sure that new developers could use that convention safely.
I would like to better understand whether your objection to the proposed
wording. Is it that it will inhibit your personal style choices or is
it that you are concerned that others in the future might interpret it
to mean their style choices are limited and that is bad for the project
in some way?
Kathey
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Rick Hillegas <Ri...@Sun.COM>.
Kathey Marsden wrote:
> First I want to say that I hope the community will continue to vote on
> this issue while discussion is underway about whether or not Rick will
> veto. I am sure the next person to take a shot at this will appreciate
> knowing where everyone stands even if it doesn't pass this round. See
> http://db.apache.org/decisions.html for responsibilities and
> definitions of voting. I think this is a consensus vote.
>
> Rick Hillegas wrote:
>
>>
>> Just want to make sure we have realistic expectations for this vote:
>> Since we are not bulk-reformatting the code, even after this vote
>> Derby won't conform to the db project guidelines.
>>
> Yes, my hope is that incrementally we can reach a point where we
> conform to the db project guidelines. The question is how much closer
> we can get to that now. I tend to think, the lack of such a
> convention for Derby was just a serious oversight in allowing Derby to
> graduate incubation.
>
>> The guidelines don't specify how extensive the hard-and-fast rules
>> have to be. To date, here are the only ones I think we have discussed
>> extensively:
>>
>> 1) No tabs.
>> 2) Indentation stops set at 4 spaces.
>> 3) Line length not to exceed 80 characters.
>>
>> To this, with the community's approval, I would add
>>
>> 0) Write clearly.
>>
>> A good enough coding standard would be these 4 hard-and-fast rules
>> plus a pointer to a non-binding style primer. Let's keep it simple
>> and focus on the issues which actually bothered us.
>>
> If incremental consensus has to start there, I suppose it could, but
> I don't think it would qualify as a "well-defined convention" and I do
> think we would need to adopt a well-defined convention in the future
> in our work to comply with the db project guidelines. I am
> curious for matters of db project guidelines, who could answer what
> level of specificity is required.
>
> I disagree that this would solve all the issues. I think still there
> would be issues with IDE's reformatting code, various religious
> discussions around particular changes and the core problem would
> remain (even after removal of the note) that a new developer can't
> rely upon setting their IDE to some documented convention and be sure
> they won't get into trouble with it. I think we need to be setup so
> it is easy to join the project and make a fix. Those making changes
> for style need to make sure that their style decisions are not going
> to interfere with anyone using the documented convention and that is
> it. That is not possible with the 4 rules and primer pointer wording.
I'm not sure I understand this point. If we recommend a style primer,
then I think we're saying that the style is safe and we don't expect
committers to flunk a conforming patch for style reasons--provided, of
course, that the code is clear. "Recommended" means "safe". I'm just
saying it doesn't mean "mandatory". I don't think our perspectives are
that far apart.
>
> It is different from closed source where we might expect some small
> group of core developers to learn how to work around and integrate
> each other's styles. ( I actually have a .emacs file that seems to
> have the beginning of this conversation years ago, I am not even sure
> who wrote it or who "I" is in this context, but it has various
> commented out sections and says .." Nat's favorite is ... Ame's said
> .... I like it like ... We still haven't decided about switch
> statements" etc.) This kind of thing does not scale well to an open
> source project with potentially hundreds of contributors all showing
> up to build great extensions and and make fixes just want to know
> some format to use that won't get them into trouble. They don't
> really care what color the shed is, just give them something that
> works and if we are not militant about it and allow variations that
> make sense and don't interfere, then we are covered.
I think we can always tighten up the rules if we discover that we are
flunking patches for recurrent reasons. So far, it's mostly been an
issue of tabs/spaces/line-lengths.
>
> I think we should publish the convention as proposed and our ultimate
> goal should be that anyone formatting their code in this way is not
> going have to ever redo their patch based on formatting issues.
Please see my earlier comment. I think we agree on this one.
"Recommended" means "safe" (provided that the patch is clear).
>
> Thanks
>
> Kathey
>
>
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Kathey Marsden <km...@sbcglobal.net>.
First I want to say that I hope the community will continue to vote on
this issue while discussion is underway about whether or not Rick will
veto. I am sure the next person to take a shot at this will appreciate
knowing where everyone stands even if it doesn't pass this round. See
http://db.apache.org/decisions.html for responsibilities and
definitions of voting. I think this is a consensus vote.
Rick Hillegas wrote:
>
> Just want to make sure we have realistic expectations for this vote:
> Since we are not bulk-reformatting the code, even after this vote
> Derby won't conform to the db project guidelines.
>
Yes, my hope is that incrementally we can reach a point where we conform
to the db project guidelines. The question is how much closer we can
get to that now. I tend to think, the lack of such a convention for
Derby was just a serious oversight in allowing Derby to graduate
incubation.
> The guidelines don't specify how extensive the hard-and-fast rules
> have to be. To date, here are the only ones I think we have discussed
> extensively:
>
> 1) No tabs.
> 2) Indentation stops set at 4 spaces.
> 3) Line length not to exceed 80 characters.
>
> To this, with the community's approval, I would add
>
> 0) Write clearly.
>
> A good enough coding standard would be these 4 hard-and-fast rules
> plus a pointer to a non-binding style primer. Let's keep it simple and
> focus on the issues which actually bothered us.
>
If incremental consensus has to start there, I suppose it could, but I
don't think it would qualify as a "well-defined convention" and I do
think we would need to adopt a well-defined convention in the future in
our work to comply with the db project guidelines. I am curious for
matters of db project guidelines, who could answer what level of
specificity is required.
I disagree that this would solve all the issues. I think still there
would be issues with IDE's reformatting code, various religious
discussions around particular changes and the core problem would
remain (even after removal of the note) that a new developer can't rely
upon setting their IDE to some documented convention and be sure they
won't get into trouble with it. I think we need to be setup so it is
easy to join the project and make a fix. Those making changes for
style need to make sure that their style decisions are not going to
interfere with anyone using the documented convention and that is it.
That is not possible with the 4 rules and primer pointer wording.
It is different from closed source where we might expect some small
group of core developers to learn how to work around and integrate each
other's styles. ( I actually have a .emacs file that seems to have the
beginning of this conversation years ago, I am not even sure who wrote
it or who "I" is in this context, but it has various commented out
sections and says .." Nat's favorite is ... Ame's said .... I like it
like ... We still haven't decided about switch statements" etc.) This
kind of thing does not scale well to an open source project with
potentially hundreds of contributors all showing up to build great
extensions and and make fixes just want to know some format to use that
won't get them into trouble. They don't really care what color the shed
is, just give them something that works and if we are not militant about
it and allow variations that make sense and don't interfere, then we are
covered.
I think we should publish the convention as proposed and our ultimate
goal should be that anyone formatting their code in this way is not
going have to ever redo their patch based on formatting issues.
Thanks
Kathey
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Rick Hillegas <Ri...@Sun.COM>.
Kathey Marsden wrote:
> Rick Hillegas wrote:
>
>> I don't want to stop the vote if we can avoid it. However, I have
>> some misgivings that we may not agree on what we're approving.
>> Everyone may be hearing what they want to hear.
>>
> I see what you are saying about folks hearing what they want to hear.
>
>> Clarity is the key goal of Derby's coding standards. The coding
>> guidelines at
>> http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html are a
>> style primer, not a law book. Mine this document for good examples
>> but use your common sense. Feel free to disregard any advice which is
>> religious in nature or which would make your code brittle. Above all
>> else, write clearly.
>>
> I don't think this wording would bring us into compliance with the db
> project guidelines that we have a "well-defined convention" and
> would create a state without a general agreed upon direction where we
> are bound to have countless discussions about code formatting
> "religion" as you put it. We need an agreed upon base color for our
> shed. If as folks are painting they feel the need to vary a bit that
> does not interfere with the general color scheme, add trim etc, that
> is reasonable, but we don't want to go back to a state where we
> encourage everyone to grab a can of whatever color paint they want and
> start painting and repainting, running colors into each other and have
> to debate about it.
Just want to make sure we have realistic expectations for this vote:
Since we are not bulk-reformatting the code, even after this vote Derby
won't conform to the db project guidelines.
The guidelines don't specify how extensive the hard-and-fast rules have
to be. To date, here are the only ones I think we have discussed
extensively:
1) No tabs.
2) Indentation stops set at 4 spaces.
3) Line length not to exceed 80 characters.
To this, with the community's approval, I would add
0) Write clearly.
A good enough coding standard would be these 4 hard-and-fast rules plus
a pointer to a non-binding style primer. Let's keep it simple and focus
on the issues which actually bothered us.
Regards,
-Rick
>
> Kathey
>
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Kathey Marsden <km...@sbcglobal.net>.
Rick Hillegas wrote:
> I don't want to stop the vote if we can avoid it. However, I have some
> misgivings that we may not agree on what we're approving. Everyone may
> be hearing what they want to hear.
>
I see what you are saying about folks hearing what they want to hear.
> Clarity is the key goal of Derby's coding standards. The coding
> guidelines at
> http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html are a
> style primer, not a law book. Mine this document for good examples but
> use your common sense. Feel free to disregard any advice which is
> religious in nature or which would make your code brittle. Above all
> else, write clearly.
>
I don't think this wording would bring us into compliance with the db
project guidelines that we have a "well-defined convention" and would
create a state without a general agreed upon direction where we are
bound to have countless discussions about code formatting "religion" as
you put it. We need an agreed upon base color for our shed. If as
folks are painting they feel the need to vary a bit that does not
interfere with the general color scheme, add trim etc, that is
reasonable, but we don't want to go back to a state where we encourage
everyone to grab a can of whatever color paint they want and start
painting and repainting, running colors into each other and have to
debate about it.
Kathey
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Daniel John Debrunner <dj...@apache.org>.
Oystein Grovlen - Sun Norway wrote:
> Rick Hillegas wrote:
>
>> Clarity is the key goal of Derby's coding standards. The coding
>> guidelines at
>> http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html are a style
>> primer, not a law book. Mine this document for good examples but use
>> your common sense. Feel free to disregard any advice which is religious
>> in nature or which would make your code brittle. Above all else, write
>> clearly.
>
> As others have stated, the reason for having coding standard is that
> the code will be easier to read if the same style is used everywhere.
> It is the same reason that words have a defined spelling. It makes
> documents much easier to read than if everyone came up with their own
> spelling. In that light, your statement is similar to the following:
>
> "The Webster's Dictionary is a spelling primer, not a law
> book. Mine this document for good examples but use your
> common sense."
I think that's too extreme, "code style" is more akin to "writing
style", not spelling.
Dan.
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Oystein Grovlen - Sun Norway <Oy...@Sun.COM>.
Rick Hillegas wrote:
> Clarity is the key goal of Derby's coding standards. The coding
> guidelines at
> http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html are a style
> primer, not a law book. Mine this document for good examples but use
> your common sense. Feel free to disregard any advice which is religious
> in nature or which would make your code brittle. Above all else, write
> clearly.
As others have stated, the reason for having coding standard is that
the code will be easier to read if the same style is used everywhere.
It is the same reason that words have a defined spelling. It makes
documents much easier to read than if everyone came up with their own
spelling. In that light, your statement is similar to the following:
"The Webster's Dictionary is a spelling primer, not a law
book. Mine this document for good examples but use your
common sense."
I think most people would accept this statement, but most people will
also feel that it is "common sense" to just follow the standard and
not come up with their own private spellings.
I do not agree that the coding guidelines contain "advice which is
religious in nature". Coding guidelines are about picking one way of
many possible ways of doing things, and it is more important that one
single way is picked than that a particular way is picked. In my
opinion, it becomes "religious" when people insist on doing it one
particular way and are not willing give up their ways for a common
standard.
Personally, I feel that the rule that tab and space usage should match
surrounding code is problematic. It will create a lot of hazzle to
switch back and forth between tabs and spaces. The argument seems to
be that this is necessary in order to be able to use tools where the
tab-width can not be configured. However, for most tools one can
solve this by redirecting the output to a file and look at that file
in a editor that has a configurable tab-width. Anyhow, I am willing
to adjust to that practice if that is needed to get a common standard.
--
Øystein
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Rick Hillegas <Ri...@Sun.COM>.
I don't want to stop the vote if we can avoid it. However, I have some
misgivings that we may not agree on what we're approving. Everyone may
be hearing what they want to hear.
I am ok with the vote continuing provided that we understand this:
Clarity is the key goal of Derby's coding standards. The coding
guidelines at
http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html are a style
primer, not a law book. Mine this document for good examples but use
your common sense. Feel free to disregard any advice which is religious
in nature or which would make your code brittle. Above all else, write
clearly.
Regards,
-Rick
Kathey Marsden wrote:
> Rick Hillegas wrote:
>
>> I am happy with this clarification.
>
>
> great! That is a relief
>
>> I would prefer that the proposal stated this explicitly so that there
>> is no confusion.
>
>
> If you are ok in principle, I'd rather not stop the vote now if we can
> avoid it. Perhaps you could propose new wording for a subsequent
> revision if you think it is important. The important thing in
> publishing a coding convention is that new developers joining the
> project can set their IDE's/editors a certain way and know if they do
> that they won't hit any tripwires. Just about every new developer in
> this project (except for you) has hit this tripwire. You were keen to
> it having navigated the course before. Most folks coming in to fix
> their bug and get out, don't have time for the traditional code
> formatting hazing ritual and I don't care to subject them to it
> anymore. This has wasted a lot of people a lot of time.
>
> Kathey
>
>
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Kathey Marsden <km...@sbcglobal.net>.
Rick Hillegas wrote:
> I am happy with this clarification.
great! That is a relief
> I would prefer that the proposal stated this explicitly so that there
> is no confusion.
If you are ok in principle, I'd rather not stop the vote now if we can
avoid it. Perhaps you could propose new wording for a subsequent
revision if you think it is important. The important thing in publishing
a coding convention is that new developers joining the project can set
their IDE's/editors a certain way and know if they do that they won't
hit any tripwires. Just about every new developer in this project
(except for you) has hit this tripwire. You were keen to it having
navigated the course before. Most folks coming in to fix their bug and
get out, don't have time for the traditional code formatting hazing
ritual and I don't care to subject them to it anymore. This has wasted
a lot of people a lot of time.
Kathey
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Rick Hillegas <Ri...@Sun.COM>.
I am happy with this clarification. I would prefer that the proposal
stated this explicitly so that there is no confusion. I think that if we
put the emphasis on clarity and common sense then we could drop the
specific exception called out for the rule on deferred variable
declarations. It is just one of the religious stands taken by these
conventions.
I thought there were some hard-and-fast rules which people wanted for
new code:
1) 4 space indentation
2) No tabs
3) 80 character lines
Is that not so?
Thanks,
-Rick
Kathey Marsden wrote:
> Rick Hillegas wrote:
>
>> -1
>>
>> On the whole, I think that the proposed guidelines are decent.
>> However, I would like us to emphasize that these are guidelines and
>> not laws.
>>
> I too think we should not be militant about this, think clarity is
> key, and don't want to see inserted layers of tools to enforce pure
> structure long term. This is why I proposed we change the
> ContributorChecklist to use the word "convention" and not "standard"
> indicating that it is a custom or practice. I think that the current
> wording captures that well and is sufficiently soft considering the
> db project guidelines actually sound much more strict
>
> from : http://db.apache.org/source.html.
>
> "
> All Java Language source code in the repository must be written in
> conformance to the " Code Conventions for the Java Programming
> Language <http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html>
> as published by Sun, or in conformance with another well-defined
> convention specified by the subproject.
> "
>
> Also, I wanted to mention that it would have been most helpful to get
> this input in response to earlier threads requesting adjustments to
> content and wording. I hope that you will reconsider whether
> further wording adjustments are needed at this point. Perhaps they
> could occur at the happy time that we take out the Note: section.
>
> Thanks
>
> Kathey
>
>
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Kathey Marsden <km...@sbcglobal.net>.
Rick Hillegas wrote:
> -1
>
> On the whole, I think that the proposed guidelines are decent.
> However, I would like us to emphasize that these are guidelines and
> not laws.
>
I too think we should not be militant about this, think clarity is key,
and don't want to see inserted layers of tools to enforce pure structure
long term. This is why I proposed we change the ContributorChecklist to
use the word "convention" and not "standard" indicating that it is a
custom or practice. I think that the current wording captures that well
and is sufficiently soft considering the db project guidelines
actually sound much more strict
from : http://db.apache.org/source.html.
"
All Java Language source code in the repository must be written in
conformance to the " Code Conventions for the Java Programming Language
<http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html> as
published by Sun, or in conformance with another well-defined convention
specified by the subproject.
"
Also, I wanted to mention that it would have been most helpful to get
this input in response to earlier threads requesting adjustments to
content and wording. I hope that you will reconsider whether further
wording adjustments are needed at this point. Perhaps they could occur
at the happy time that we take out the Note: section.
Thanks
Kathey
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Rick Hillegas <Ri...@Sun.COM>.
-1
On the whole, I think that the proposed guidelines are decent. However,
I would like us to emphasize that these are guidelines and not laws.
1) If we want to adopt a set of laws, then brevity is the soul of wit.
The hard-and-fast laws should fit on a single page so that you can know
at a glance what conforms.
2) The key goal is clarity. This does not come across in these
guidelines. Sometimes you have to break guidelines in order to be clear.
This is the chief piece of advice from Strunk and White's The Elements
of Style and from Kernighan's The Elements of Programming Style.
3) There are some religious doctrines in the proposed guidelines. Brace
placement, in particular, is purely a matter of style. Let's leave that
to the individual's taste. I would not outlaw the following code
snippet. In my opinion it is a model piece of code, concise and clear,
even though it violates the proposed bracing religion:
if ( featureEnabled ) { return; }
-Rick
Kathey Marsden wrote:
> This is a vote to define the coding conventions for the Derby project
> per the db project guidelines http://db.apache.org/source.html
> Vote closes 10:00am, Wednesday, August 15.
>
> [+1] Adopt the coding convention described.
> [-1 ] Do not adopt the coding convention described.
>
> The conventions outlined below will be published on the wiki page
> http://wiki.apache.org/db-derby/DerbyContributorChecklist
>
> 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.
>
>
>
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Kathey Marsden <km...@sbcglobal.net>.
Manish Khettry wrote:
>I see that we're deferring tabs vs spaces and the "{"
>position issue for later.
>
>
>
The convention does cover the "{" position. and the long term strategy
for spaces vs tabs.
Inspired by the Wiki
http://wiki.apache.org/db-derby/IncrementalDevelopment page,
I am trying the IncrementalConcensus approach #:)
Steps are:
1) Decide upon long term coding conventions (This vote)
2) Determine long term strategy for consistent code formating and
spacing of the code. (My initial thought is reformat all the codelines
but there is debate on this point. Other solutions may present themselves)
3) Assuming some large scale action is needed, recruit some detail
oriented volunteer to perform the deed when it needs to occur. (Such a
task is not in my skill set)
4) Gain consensus on a date for the large scale action if needed.
5) Volunteer executes large scale action if needed.
6) Remove the "Note:" section of the convention.
7) Put this whole mess behind us and enjoy a world without white space
diffs wasting everyones time, impeding review, and hiding bugs in the
product.
Of course how far we get down this path remains to be seen. I think
each incremental step achieved will be useful even if we get stuck along
the way.
Kathey
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Manish Khettry <ma...@yahoo.com>.
+1
I see that we're deferring tabs vs spaces and the "{"
position issue for later.
--- Andrew McIntyre <mc...@gmail.com> wrote:
> On 8/11/06, Kathey Marsden
> <km...@sbcglobal.net> wrote:
> > This is a vote to define the coding conventions
> for the Derby project
> > per the db project guidelines
> http://db.apache.org/source.html
> > Vote closes 10:00am, Wednesday, August 15.
> >
> > [+1] Adopt the coding convention described.
> > [-1 ] Do not adopt the coding convention
> described.
> >
> > The conventions outlined below will be published
> on the wiki page
> >
>
http://wiki.apache.org/db-derby/DerbyContributorChecklist
> >
> > 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.
>
> +1
>
> andrew
>
__________________________________________________
Do You Yahoo!?
Tired of spam? Yahoo! Mail has the best spam protection around
http://mail.yahoo.com
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Andrew McIntyre <mc...@gmail.com>.
On 8/11/06, Kathey Marsden <km...@sbcglobal.net> wrote:
> This is a vote to define the coding conventions for the Derby project
> per the db project guidelines http://db.apache.org/source.html
> Vote closes 10:00am, Wednesday, August 15.
>
> [+1] Adopt the coding convention described.
> [-1 ] Do not adopt the coding convention described.
>
> The conventions outlined below will be published on the wiki page
> http://wiki.apache.org/db-derby/DerbyContributorChecklist
>
> 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.
+1
andrew
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Olav Sandstaa <ol...@sun.com>.
Kathey Marsden wrote:
> This is a vote to define the coding conventions for the Derby project
> per the db project guidelines http://db.apache.org/source.html
> Vote closes 10:00am, Wednesday, August 15.
>
> [+1] Adopt the coding convention described.
> [-1 ] Do not adopt the coding convention described.
[+1] Adopt the coding convention described.
Olav
Re: [VOTE] Approve coding conventions for the Derby project
Posted by David Van Couvering <Da...@Sun.COM>.
+1
(with the grumble that switching between tabs and spaces is onerous,
especially in my IDE where I just can't tell the difference. But I
recognize we'll be addressing that later)
Kathey Marsden wrote:
> This is a vote to define the coding conventions for the Derby project
> per the db project guidelines http://db.apache.org/source.html
> Vote closes 10:00am, Wednesday, August 15.
>
> [+1] Adopt the coding convention described.
> [-1 ] Do not adopt the coding convention described.
>
> The conventions outlined below will be published on the wiki page
> http://wiki.apache.org/db-derby/DerbyContributorChecklist
>
> 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.
>
>
>
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Manish Khettry <ma...@gmail.com>.
>
> I do think the space/tab issue causes headaches. We could just document
> it, but I actually think we should reformat the code with respect to
> tabstop and just move to spaces. I wish we were attacking the root
> problems causing people pain up front. What I see as problems are:
> 1) space/tab issue is causing problems. Some tools just don't like 4
> space tabs.
> 2) do not make review/commit job harder by doing format changes along
> with "real" code changes.
I do agree with Mike that tabs/spaces is whats causing headaches and if we
fixed that first, we'd be better off.
Anyway, as far as coding conventions go-- I'd rather that we adopt one and
try and move the code to conform that. In my experience, if all (or most of
the code) looks sort of similar, it is easier to read. I don't care where
people put the brace, long as everyone puts it in the same place. This is
just my experience-- if people think "write clean code" is a good enough
convention, then so be it.
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Mike Matrigali <mi...@sbcglobal.net>.
my vote:-0
I continue to struggle with this issue. I don't think we should
reformat the style of all the existing code, it is going to cause
merge hell. But
if we don't why vote yes for this proposal as then it is just a lie
saying " Derby uses the "Code Conventions for the Java Programming
Language" (http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html)
... ". So I am unclear on what I am voting on. Is it just the
following code convention is a perfectly acceptable way to submit
derby code, as well there might be others?
I haven't voted -1 as I don't have a better suggestion for a standard,
other than the code in a file should be clear and consistent. Even
things I particularly don't like, like 80+ character lines are sometimes
more clear than hoops to make them less than 80 character.
I do think the space/tab issue causes headaches. We could just document
it, but I actually think we should reformat the code with respect to
tabstop and just move to spaces. I wish we were attacking the root
problems causing people pain up front. What I see as problems are:
1) space/tab issue is causing problems. Some tools just don't like 4
space tabs.
2) do not make review/commit job harder by doing format changes along
with "real" code changes.
Kathey Marsden wrote:
> This is a vote to define the coding conventions for the Derby project
> per the db project guidelines http://db.apache.org/source.html
> Vote closes 10:00am, Wednesday, August 15.
>
> [+1] Adopt the coding convention described.
> [-1 ] Do not adopt the coding convention described.
>
> The conventions outlined below will be published on the wiki page
> http://wiki.apache.org/db-derby/DerbyContributorChecklist
>
> 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.
>
>
>
>
>
Re: [VOTE] Approve coding conventions for the Derby project
Posted by "Bernt M. Johnsen" <Be...@Sun.COM>.
My vote: -0
I'm not too fond of coding conventions, ecpecially when they're as large
as this one. The amendments are ok, though.
BTW: I think the most important rule is in a note in Kathey's call for
vote: "Patches should not have white space diffs." The second most
important rule I would prefer to be "Use common sense".
Kathey Marsden wrote:
> This is a vote to define the coding conventions for the Derby project
> per the db project guidelines http://db.apache.org/source.html
> Vote closes 10:00am, Wednesday, August 15.
>
> [+1] Adopt the coding convention described.
> [-1 ] Do not adopt the coding convention described.
>
> The conventions outlined below will be published on the wiki page
> http://wiki.apache.org/db-derby/DerbyContributorChecklist
>
> 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.
>
>
>
--
Bernt Marius Johnsen, Database Technology Group,
Staff Engineer, Technical Lead Derby/Java DB
Sun Microsystems, Trondheim, Norway
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Kathey Marsden <km...@sbcglobal.net>.
Daniel John Debrunner wrote:
>I think these are some of the problems:
>
>
>
I would add
4) Contributors (especially those that are new or not religious about
these things) do not a have a safe setting for their editor that they
can use and know that things will work, be safe and generally not cause
their patch to be bounced back based on formatting issues.
This is the problem that I would like to be solved.
Kathey
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Daniel John Debrunner <dj...@apache.org>.
Kathey Marsden wrote:
> This is a vote to define the coding conventions for the Derby project
> per the db project guidelines http://db.apache.org/source.html
> Vote closes 10:00am, Wednesday, August 15.
It's interesting seeing the discussion on this and it some ways it
circling back to the original Cloudscape coding standard which was
"write clear code (with tab stops as four)" and really is the current
hidden implict current Derby standard.
It's also a little strange that the items that people seem to like most
are the *exceptions* to Sun's standards. I agree the exceptions are
good, which leads to the question why are we using those standards.
Also looking back through the discussion it's not obvious to me what
problems we are trying to solve, just blindly following the DB
guidelines is not a good reason. If we documented the implict standard
today then we would be in lines with the DB guidelines (IMHO).
I know there are problems, maybe if we started with those, not a
solution we might get somewhere. I think these are some of the problems:
1) Patches are submitted with changes not related to the issue in hand,
especially with white space diffs.
2) Patch files tend to be confusing to read when the code contains a
mixture of spaces and tabs for indentation (e.g. new code has spaces,
surrounding code has tabs)
3) People looking at the code don't know the tab-stop is meant to be at
four so the code looks messed up to them (probably leading to 1).
Dan.
Re: [VOTE] Approve coding conventions for the Derby project
Posted by Narayanan <V....@Sun.COM>.
Kathey Marsden wrote:
> This is a vote to define the coding conventions for the Derby project
> per the db project guidelines http://db.apache.org/source.html
> Vote closes 10:00am, Wednesday, August 15.
>
> [+1] Adopt the coding convention described.
> [-1 ] Do not adopt the coding convention described.
>
[+1] Adopt the coding convention described.
Narayanan