Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-27 Thread Jim Fulton


On Aug 23, 2007, at 8:37 PM, Philipp von Weitershausen wrote:

We have 100+ packages that make up what used to be distributed as  
Zope3. We have numerous more packages in svn.zope.org. Most of  
them are developed, released and distributed individually. We like  
to think this is a good thing (I certainly do). But currently we  
have a bit of a chaos [2]. It's not bad, but I fear without some  
guidance, it'll get worse.


Christian Theune recently wrote a document [1] in which he outlined  
how we should get to a development process and what topics it  
should touch.  This document is very hands-on and describes actions  
that should be taken to reach these goals. I've taken the liberty  
to jump ahead and write down some current practices:


http://svn.zope.org/*checkout*/Sandbox/philikon/foundation/ 
maintaining-software.txt


This is a great start. Thanks!

A few small points:

- I'm going to mostly stay out of the style debate except to note  
that the Zope style guide builds on PEP8.  It doesn't disagree with  
it much accept in the case of some naming, due to the fact that the  
ZSG made a commitment before PEP8 did.


- On doctest, there should be greater emphasis on there being 2 kinds  
of tests, executable documentation and other tests.  I think there is  
value in executable documentation, but it should be documentation  
first.  A lot of our doctests that we think/wish are documentation  
are not very good documentation.  We need to do a better job of this.


I do feel strongly that even non-documentation tests should be  
written in a fairly literate way with documentation of the test  
itself,  I strongly prefer the doctest format for these tests, but I  
don't want to be an evil dictator about it. I suggest that classic  
unit tests can be used for new tests, but *only* if they are well  
documented.  I've never seen a classic unit test that was, but I'm  
open to the theoretical possibility. :)

BTW, I've seen poorly documented doctests too.

Jim

--
Jim Fulton  mailto:[EMAIL PROTECTED]Python 
Powered!
CTO (540) 361-1714  
http://www.python.org
Zope Corporationhttp://www.zope.com http://www.zope.org



___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-27 Thread Philipp von Weitershausen

On 25 Aug 2007, at 19:01 , Jim Fulton wrote:


On Aug 23, 2007, at 8:37 PM, Philipp von Weitershausen wrote:

We have 100+ packages that make up what used to be distributed as  
Zope3. We have numerous more packages in svn.zope.org. Most of  
them are developed, released and distributed individually. We like  
to think this is a good thing (I certainly do). But currently we  
have a bit of a chaos [2]. It's not bad, but I fear without some  
guidance, it'll get worse.


Christian Theune recently wrote a document [1] in which he  
outlined how we should get to a development process and what  
topics it should touch.  This document is very hands-on and  
describes actions that should be taken to reach these goals. I've  
taken the liberty to jump ahead and write down some current  
practices:


http://svn.zope.org/*checkout*/Sandbox/philikon/foundation/ 
maintaining-software.txt


This is a great start. Thanks!

A few small points:

- I'm going to mostly stay out of the style debate except to note  
that the Zope style guide builds on PEP8.  It doesn't disagree with  
it much accept in the case of some naming, due to the fact that the  
ZSG made a commitment before PEP8 did.


It seems to me that we should certainly reference the ZSG in the  
guide. Contrary to previous comments, I do believe that the ZSG could  
use some cleanup and could be made more concise. Since the  
differences mostly seem to revolve around method and function naming,  
I'm almost inclined to leave it open to the package authors whether  
to choose camelCase (ZSG) or under_score (PEP8) naming, as long as  
it's consistent within a pacakge.


- On doctest, there should be greater emphasis on there being 2  
kinds of tests, executable documentation and other tests.  I think  
there is value in executable documentation, but it should be  
documentation first.  A lot of our doctests that we think/wish are  
documentation are not very good documentation.  We need to do a  
better job of this.


I do feel strongly that even non-documentation tests should be  
written in a fairly literate way with documentation of the test  
itself,  I strongly prefer the doctest format for these tests, but  
I don't want to be an evil dictator about it. I suggest that  
classic unit tests can be used for new tests, but *only* if they  
are well documented.  I've never seen a classic unit test that was,  
but I'm open to the theoretical possibility. :)

BTW, I've seen poorly documented doctests too.


Thanks for the feedback. I've improved the Automated tests section  
accordingly. Could you check it again and see if I captured your  
comments right?


___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-26 Thread Christian Theune
Am Samstag, den 25.08.2007, 17:57 -0400 schrieb Zvezdan Petkovic:
 Obviously, a visual perception differs from person to person.  If a 
 person has a difficulty reading getMainType(), they should not be 
 forced to write get_main_type() in their Zope code for the sake of 
 consistency which is in this particular issue non-existent.

With in their Zope code you mean code they write for themselves or for
the Zope project? I'm happy to set my personal style favorites aside
when working on a shared project. I hate code that is inconsistent more
than I like my personal preferences (which are very near to PEP 8
anyway). 

I think there's a social issue around the corner.


___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-26 Thread Christian Theune
Am Sonntag, den 26.08.2007, 21:52 +0200 schrieb Christian Theune:
 Am Samstag, den 25.08.2007, 17:57 -0400 schrieb Zvezdan Petkovic:
  Obviously, a visual perception differs from person to person.  If a 
  person has a difficulty reading getMainType(), they should not be 
  forced to write get_main_type() in their Zope code for the sake of 
  consistency which is in this particular issue non-existent.
 
 With in their Zope code you mean code they write for themselves or for
 the Zope project? I'm happy to set my personal style favorites aside
 when working on a shared project. I hate code that is inconsistent more
 than I like my personal preferences (which are very near to PEP 8
 anyway). 
 
 I think there's a social issue around the corner.

Please don't answer to me, something in this thread made my mail reader
throw the reply mails in a bad order so I thought this part of the
conversation was over although there were more mails in a different
tree. 

Everything that needs to be said from my point of view was said by other
people, I don't want to resurrect this.


___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-25 Thread Dieter Maurer
Andreas Jung wrote at 2007-8-24 21:01 +0200:
 ...
ACK on everything of that. But reading code comes before understanding code.
And the visual impression of code has a strong impact on how we read code 
and on how we understand code.

True, but do you really read code to satisfy an esthetical need?

When I read code, I always need an understanding of this code -- usually
because the code does not what I suppose it should do. I never
read code just for pleasure.

Reading effort is usually much smaller than the understanding effort.


While many people in the Python community seem to prefer loose code,
I can better read and understand dense code.

I can also read and understand loose code and my total effort
is not dominated by the reading part. Thus, I could e.g. analyse
a postgres (locking) problem by understanding its source
although the code was horribly loose
because the other (much more essential) aspects have been excellent:
like conceptial documentation, well chosen names, well documented source...


While I do not tell others whether they should write loose or dense
code, I refuse to follow their preferences in *my* code.


You can specify rules for your repositories -- and I will obey them.
If the rules go however significantly against my
preferences, then this implies fewer contributions from my side.



-- 
Dieter
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-25 Thread Dieter Maurer
Philipp von Weitershausen wrote at 2007-8-24 20:24 +0200:
 ...
I wonder how you can like this language with significant whitespaces  
and lots of underscore rules then :).

In fact, I dislike Python's grouping by indentation (especially how
it is implemented in the interactive interpreter) and
a few other syntactical aspects (e.g. the need to explicitly
specify the object parameter in a method definition).
But other aspects are very nice and outweigh the syntactical nastiness.

I do not see lots of underscore rules, maybe because I disregard PEP 8...
For me, the Java style (getMainType) is easier readable than
the one prefered in the Python runtime library (get_main_type).



-- 
Dieter
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-25 Thread Benji York

Fred Drake wrote:

On 8/24/07, Stephan Richter [EMAIL PROTECTED] wrote:

But if you prefer consistency, then we really should be staying with the Zope
3 style guide,


This, of course, all depends on the answer to the question:
Consistency with what?  Zope 3 history?  The larger Python community?
(Don't think the world agrees on PEP 8...)


Because my desire is to make individual Zope packages more widely 
adopted by the larger Python community and bring more people to Zope 3, 
I prefer PEP 8.  As has been said of Python, more Python code will be 
written in the future than has been in the past, I hope the same is true 
of Zope.   Hopefully, there are also more Zope users to come than we 
have ever had.


Consistency is good, but we have to be consistent with the largest body 
of code/group of people as possible.

--
Benji York
Senior Software Engineer
Zope Corporation
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-25 Thread Andreas Jung



--On 25. August 2007 08:51:44 -0400 Benji York [EMAIL PROTECTED] wrote:


Fred Drake wrote:

On 8/24/07, Stephan Richter [EMAIL PROTECTED] wrote:

But if you prefer consistency, then we really should be staying with
the Zope 3 style guide,


This, of course, all depends on the answer to the question:
Consistency with what?  Zope 3 history?  The larger Python community?
(Don't think the world agrees on PEP 8...)


Because my desire is to make individual Zope packages more widely
adopted by the larger Python community and bring more people to Zope 3, I
prefer PEP 8.  As has been said of Python, more Python code will be
written in the future than has been in the past, I hope the same is true
of Zope.   Hopefully, there are also more Zope users to come than we have
ever had.

Consistency is good, but we have to be consistent with the largest body
of code/group of people as possible.



Can someone please point out the major differences concerning Python code
between PEP 8 and the Zope 3 style guide?

-aj 

pgpl3EWCRn8Tj.pgp
Description: PGP signature
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-25 Thread Benji York

Andreas Jung wrote:

Can someone please point out the major differences concerning Python code
between PEP 8 and the Zope 3 style guide?


The primary differences are in method, attribute, function, and variable 
names.  PEP 8 specifies lower_case_with_underscores.


Zope 3, more often than not (as noted by others, inconsistencies 
exists), follows these conventions:


http://wiki.zope.org/zope3/ZopePythonNamingConventions specifies 
CamelCase for Public global variables (not exactly sure what all that 
encompasses) and lower_case_with_underscores for local variables.  The 
same page prescribes mixedCase for module-level (non-factory) functions.


http://wiki.zope.org/zope3/ClassesAttributesMethods specifies mixedCase 
for attributes and methods.


BTW: http://wiki.zope.org/zope3/CodingStyle (like most of the Wiki) is a 
mess.  I may cut out some outdated chunks (including 5 year old 
comments) if no one objects.  Are there any guidelines for the wiki?  I 
looked but couldn't find any.

--
Benji York
Senior Software Engineer
Zope Corporation
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-25 Thread Zvezdan Petkovic
On Saturday 25 August 2007 06:31, Dieter Maurer wrote:
 I do not see lots of underscore rules, maybe because I disregard PEP
 8... For me, the Java style (getMainType) is easier readable than
 the one prefered in the Python runtime library (get_main_type).

Some people feel that theyCannotReadThisAndItShowsInASpellChecker and 
therefore can_read_and_spell_this_much_better is their choice, 
otherwise weWouldWriteAllSpokenLanguagesAndBooksThatWayForReadability.  
You could say that they come from a C background or that they are 
a little older.  :-)

Some other people say, e.g., those who come from Java background, that 
readingTheNamesLikeThisIsNotAProblemAtAll and they prefer that style.  
I'm sure we all heard the arguments pro and contra more times than we 
care to hear.

Obviously, a visual perception differs from person to person.  If a 
person has a difficulty reading getMainType(), they should not be 
forced to write get_main_type() in their Zope code for the sake of 
consistency which is in this particular issue non-existent.

This is really the least important style issue.

Best regards,
--
Zvezdan Petkovic
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-25 Thread Zvezdan Petkovic
On Saturday 25 August 2007 09:48, Benji York wrote:
 Andreas Jung wrote:
  Can someone please point out the major differences concerning
  Python code between PEP 8 and the Zope 3 style guide?

 The primary differences are in method, attribute, function, and
 variable names.  PEP 8 specifies lower_case_with_underscores.

 Zope 3, more often than not (as noted by others, inconsistencies
 exists), follows these conventions:

 http://wiki.zope.org/zope3/ZopePythonNamingConventions specifies
 CamelCase for Public global variables (not exactly sure what all
 that encompasses) and lower_case_with_underscores for local
 variables.  The same page prescribes mixedCase for module-level
 (non-factory) functions.

 http://wiki.zope.org/zope3/ClassesAttributesMethods specifies
 mixedCase for attributes and methods.

FWIW, the Zope3 style guide on that wiki page states explicitly in the 
first paragraph that Python Style Guide is used for all issues that are 
not mentioned, and then continues to say that most of the code in 
Zope 3 so far uses CamelCase instead of names_as_this.

The way I read this, it's most of the code so far uses, rather than
all code must/should use.  It's a *description* of the current state
rather than the *prescription* to do it in CamelCase.
Perhaps the intent to prescribe should have been stated explicitly,
but currently it isn't, it's only nudged towards a new user.

I also think this is the least worthy of style issues to pursue because 
it affects the reader's visual perception.  All of us have different 
visual perceptions, some of us have bad eyes or some other reason to 
find one easier to read than other.  Please see my other message in 
this thread on this.

+1 for Benji's preference of PEP-8.

Best regards,
--
Zvezdan Petkovic
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Philipp von Weitershausen

On 24 Aug 2007, at 07:05 , Andreas Jung wrote:
--On 24. August 2007 02:37:01 +0200 Philipp von Weitershausen  
[EMAIL PROTECTED] wrote:


http://svn.zope.org/*checkout*/Sandbox/philikon/foundation/ 
maintaining-so

ftware.txt



Thanks for writing this excellent guide. However I am personally  
unclear
about specifying the dependencies and their version requirements  
(but this is more a setuptools issue than a Z3 specific one).


You're absolutely right, this should be addressed by the guide. I've  
added it to the Missing subjects list at the end of the document.  
Dependency management also touches the whole known working set  
problem that Christian mentioned in his document. We really need to  
start thinking about it (a recent grok release made me aware of how  
badly we need it). I will try and bring up some use cases for this.


Other missing subjects of the guide are

* version numbering schemes (I expect this to be a no-brainer, I just  
need to write it down),


* the policy on backward compatibility and deprecation (Here I'm  
planning on paraphrasing Jim's recent email to the list [1]).



[1] http://mail.zope.org/pipermail/zope3-dev/2007-August/023364.html

___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Stephan Richter
On Thursday 23 August 2007 20:37, Philipp von Weitershausen wrote:
 I would like to get your comments on it. No matter what this evolves to,
 I wouldn't mind eventually seeing it set in stone with your blessings,
 so that the checkin police can use it as the highway code to issue
 tickets to anyone who's speeding on the repository lane.

I don't like the section on coding style. A while back we agreed that people 
can choose it freely as long as every package in the *namespace* has the same 
style. So for example, ``zope`` and ``z3c`` use the original Zope 3 
styleguide, while ``zc`` uses PEP8 compliance.

This is much easier to keep track of than having to remember every package's 
style.

I personally do not like underscore-style method naming, so I would never use 
it for packages that I am starting from scratch. I do honor other people's 
decisions though, and would always follow the original author's style. 
Consistency is better than correctness in this case. (I usually tend to value 
correctness higher than consistency.)

Regards,
Stephan
-- 
Stephan Richter
CBU Physics  Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Philipp von Weitershausen

On 24 Aug 2007, at 15:25 , Stephan Richter wrote:

On Thursday 23 August 2007 20:37, Philipp von Weitershausen wrote:
I would like to get your comments on it. No matter what this  
evolves to,
I wouldn't mind eventually seeing it set in stone with your  
blessings,

so that the checkin police can use it as the highway code to issue
tickets to anyone who's speeding on the repository lane.


I don't like the section on coding style. A while back we agreed  
that people
can choose it freely as long as every package in the *namespace*  
has the same

style.


Hmm, I recall having discussed this on the list at some point. I  
don't recall having reached an agreement. That could be me, though...


So for example, ``zope`` and ``z3c`` use the original Zope 3  
styleguide, while ``zc`` uses PEP8 compliance.


So does this mean I'll can't put my stuff in the 'z3c' namespace if I  
want to use PEP8 (which I do, not because of personal preference but  
because of consistency)?


This is much easier to keep track of than having to remember every  
package's

style.

I personally do not like underscore-style method naming, so I would  
never use

it for packages that I am starting from scratch.


This and other aspects are things I don't particularly love about  
PEP8 either, but I value consistency over my personal preferences.



I do honor other people's
decisions though, and would always follow the original author's style.
Consistency is better than correctness in this case. (I usually  
tend to value

correctness higher than consistency.)


Well, this may sound harsh, but I see some appeal in actually forcing  
a particular coding-style on everybody. It's soo late for anything  
that has been started already, but I don't see a reason why we simply  
can't say:


  If you start a new project on svn.zope.org, it'll have to be in  
PEP8 styling.


The rule being behind this (as already mentioned above), that  
consistency values higher than personal preferences.




___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Stephan Richter
On Friday 24 August 2007 09:34, Philipp von Weitershausen wrote:
 Well, this may sound harsh, but I see some appeal in actually forcing  
 a particular coding-style on everybody.

That's not harsh. That's the point of a coding style. :-) The long-term 
benefits are greater.

 It's soo late for anything   
 that has been started already, but I don't see a reason why we simply  
 can't say:

    If you start a new project on svn.zope.org, it'll have to be in  
 PEP8 styling.

 The rule being behind this (as already mentioned above), that  
 consistency values higher than personal preferences.

But if you prefer consistency, then we really should be staying with the Zope 
3 style guide, which is effectively PEP 8 with camel case methods, functions 
and attributes. Also, the Zope 3 style guide does more than PEP 8 as it 
discusses other files and package structure as well. So, maybe we should 
write another official ZF document with our style guide capturing the result 
of this discussion.

Oh, I forgot to comment on the z3c namespace: I was expecting this 
response. ;-) This is one of the bite-the-bullet cases I am torn about too, 
since I want to encourage people checking in stuff into z3c -- as a here is 
my stuff namespace -- but on the other hand I do like consistency.

That said, I guess I could retrieve from one style for a namespace in the 
interest of keeping z3c open for all to contribute to. But I certainly would 
not switch to PEP8; we worked too hard to make the original Zope 3 tree Zope 
3 style guide compliant (mostly me running after Jim reminding him -- 
failures to do so are seen in a few packages like zope.schema ;-).

Regards,
Stephan 
-- 
Stephan Richter
CBU Physics  Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Andreas Jung



--On 24. August 2007 09:25:14 -0400 Stephan Richter 
[EMAIL PROTECTED] wrote:



On Thursday 23 August 2007 20:37, Philipp von Weitershausen wrote:

I would like to get your comments on it. No matter what this evolves to,
I wouldn't mind eventually seeing it set in stone with your blessings,
so that the checkin police can use it as the highway code to issue
tickets to anyone who's speeding on the repository lane.


I don't like the section on coding style. A while back we agreed that
people  can choose it freely as long as every package in the *namespace*
has the same  style. So for example, ``zope`` and ``z3c`` use the
original Zope 3  styleguide, while ``zc`` uses PEP8 compliance.

This is much easier to keep track of than having to remember every
package's  style.

I personally do not like underscore-style method naming, so I would never
use  it for packages that I am starting from scratch. I do honor other
people's  decisions though, and would always follow the original author's
style.  Consistency is better than correctness in this case. (I usually
tend to value  correctness higher than consistency.)



We should not be too pendantic when it comes to coding styles. I assume 
that most contributors to Zope 3 or Zope components know how to write code 
the Zope 3 way. Now with Philipp's guide we have a document telling people 
how to do it the right way. We still have the stick in our bag for the case 
of the cases...


Andreas




pgpod7hrA09mA.pgp
Description: PGP signature
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Fred Drake
On 8/24/07, Andreas Jung [EMAIL PROTECTED] wrote:
 We should not be too pendantic when it comes to coding styles. I assume
 that most contributors to Zope 3 or Zope components know how to write code
 the Zope 3 way.

As the community grows, this is an increasingly poor assumption.
Different developers come to Zope with different background experience
and from environments that have their own coding styles.

 Now with Philipp's guide we have a document telling people
 how to do it the right way.

I don't think that's what this is.  This is a document describing how
things /are/ done in the Zope 3 repository.  That's helpful both as it
stands and as a foundation for a document on how things should be
going forward.

This has nothing to do about what's the right way; it's about what's
the agreed-upon way.  Very different.  Everybody already knows the
right way, they just can't agree on it.  :-)


  -Fred

-- 
Fred L. Drake, Jr.fdrake at gmail.com
Chaos is the score upon which reality is written. --Henry Miller
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Andreas Jung



--On 24. August 2007 12:21:24 -0400 Fred Drake [EMAIL PROTECTED] wrote:


On 8/24/07, Andreas Jung [EMAIL PROTECTED] wrote:

We should not be too pendantic when it comes to coding styles. I assume
that most contributors to Zope 3 or Zope components know how to write
code the Zope 3 way.


As the community grows, this is an increasingly poor assumption.
Different developers come to Zope with different background experience
and from environments that have their own coding styles.


My statement was focused on discussions like camel case vs. underscores.
Such discussions are basically academic. In real life when you develop
software for different companies or projects it is hard to switch your
personal coding styles from project to project. In my experience you adopt
the Zope 3 style guide also to other projects outside the Zope world.
But let's be pragmatic at some point...




Now with Philipp's guide we have a document telling people
how to do it the right way.


I don't think that's what this is.  This is a document describing how
things /are/ done in the Zope 3 repository.  That's helpful both as it
stands and as a foundation for a document on how things should be
going forward.


What's the difference? :-)

-aj



pgp9faw3M2D4R.pgp
Description: PGP signature
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Fred Drake
On 8/24/07, Stephan Richter [EMAIL PROTECTED] wrote:
 That's not harsh. That's the point of a coding style. :-) The long-term
 benefits are greater.

Agreed!

 But if you prefer consistency, then we really should be staying with the Zope
 3 style guide,

This, of course, all depends on the answer to the question:
Consistency with what?  Zope 3 history?  The larger Python community?
(Don't think the world agrees on PEP 8...)

 which is effectively PEP 8 with camel case methods, functions
 and attributes. Also, the Zope 3 style guide does more than PEP 8 as it
 discusses other files and package structure as well. So, maybe we should
 write another official ZF document with our style guide capturing the result
 of this discussion.

Maybe.

 That said, I guess I could retrieve from one style for a namespace in the
 interest of keeping z3c open for all to contribute to. But I certainly would
 not switch to PEP8; we worked too hard to make the original Zope 3 tree Zope

What bugs me most is that changing the style used keeps coming up;
it's silly to keep trying to change it.  *That* is what defeats the
benefits of having one to start with.

I don't really care whether the style is the classic Zope 3 style or
PEP 8, as long as it never changes.


  -Fred

-- 
Fred L. Drake, Jr.fdrake at gmail.com
Chaos is the score upon which reality is written. --Henry Miller
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Fred Drake
On 8/24/07, Andreas Jung [EMAIL PROTECTED] wrote:
 My statement was focused on discussions like camel case vs. underscores.
 Such discussions are basically academic.

Agreed.

 In real life when you develop
 software for different companies or projects it is hard to switch your
 personal coding styles from project to project. In my experience you adopt
 the Zope 3 style guide also to other projects outside the Zope world.

For new projects, perhaps.  If Zope 3 work is your primary thing.  If
the other projects don't have established styles.  That's often not
the case, though.

 But let's be pragmatic at some point...

Right.  Adopt *one* style, due to the long-term benefits, and don't change it.


  -Fred

-- 
Fred L. Drake, Jr.fdrake at gmail.com
Chaos is the score upon which reality is written. --Henry Miller
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Stephan Richter
On Friday 24 August 2007 12:21, Fred Drake wrote:
 I don't think that's what this is.  This is a document describing how
 things /are/ done in the Zope 3 repository.  That's helpful both as it
 stands and as a foundation for a document on how things should be
 going forward.

 This has nothing to do about what's the right way; it's about what's
 the agreed-upon way.  Very different.  Everybody already knows the
 right way, they just can't agree on it.  :-)

Well said! :-)

Regards,
Stephan
-- 
Stephan Richter
CBU Physics  Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Stephan Richter
On Friday 24 August 2007 12:59, Fred Drake wrote:
  But let's be pragmatic at some point...

 Right.  Adopt *one* style, due to the long-term benefits, and don't change
 it.

I totally agree. It was the main reason for the original style guide for Zope 
3; but you both were around when we worked on it, so I am preaching to the 
choir.

Based on Fred's comment, it should be the Zope 3 styleguide then.

Regards,
Stephan 
-- 
Stephan Richter
CBU Physics  Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Stephan Richter
On Friday 24 August 2007 12:55, Fred Drake wrote:
 I don't really care whether the style is the classic Zope 3 style or
 PEP 8, as long as it never changes.

He he, except that the ``zc`` namespace started using PEP 8. ;-) I am pretty 
sure the vast majority of code in the repos is classic Zope 3. ``zope``, 
``z3c`` (for most parts), and ``lovely`` all follow Zope 3.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics  Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Fred Drake
On 8/24/07, Stephan Richter [EMAIL PROTECTED] wrote:
 He he, except that the ``zc`` namespace started using PEP 8. ;-) I am pretty
 sure the vast majority of code in the repos is classic Zope 3. ``zope``,
 ``z3c`` (for most parts), and ``lovely`` all follow Zope 3.

Even worse, the ``zc`` namespace has multiple-personality disorder
(MPD; ``zope.formlib`` exhibits this as well); there is no single
style use throughout.  I attribute this to fact that the style
question even came up after the Zope 3 style guide was written.

There are some people who thought there was an agreement that PEP 8
would be used in the ``zc`` package, but it wasn't communicated to
everyone at ZC, and was never consistently applied.  The resulting MPD
has only feed the confusion.  :-(


  -Fred

-- 
Fred L. Drake, Jr.fdrake at gmail.com
Chaos is the score upon which reality is written. --Henry Miller
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Dieter Maurer
Philipp von Weitershausen wrote at 2007-8-24 15:34 +0200:
 ...
This and other aspects are things I don't particularly love about  
PEP8 either, but I value consistency over my personal preferences.

 I do honor other people's
 decisions though, and would always follow the original author's style.
 Consistency is better than correctness in this case. (I usually  
 tend to value
 correctness higher than consistency.)

Well, this may sound harsh, but I see some appeal in actually forcing  
a particular coding-style on everybody. It's soo late for anything  
that has been started already, but I don't see a reason why we simply  
can't say:

   If you start a new project on svn.zope.org, it'll have to be in  
PEP8 styling.

The rule being behind this (as already mentioned above), that  
consistency values higher than personal preferences.

Sure, you can say it...
But, you will loose some packages...

I find it very stupid to prescribe whilespace rules and
'_' separation versus camelCase spelling.



-- 
Dieter
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Andreas Jung



--On 24. August 2007 19:27:23 +0200 Dieter Maurer [EMAIL PROTECTED] 
wrote:


I find it very stupid to prescribe whilespace rules and


Whitespace rules have a major impact on the readability of code.
Readability is a major point when we talk of code quality. Readable code 
does not make code automatically but good code has to be readable.



'_' separation versus camelCase spelling.


Ack.

-aj

pgpic2FxlUE9h.pgp
Description: PGP signature
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Dieter Maurer
Andreas Jung wrote at 2007-8-24 19:35 +0200:
 ...
Whitespace rules have a major impact on the readability of code.
Readability is a major point when we talk of code quality. Readable code 
does not make code automatically but good code has to be readable.

Lots of whitespace does not make the code more readable for all
persons -- it does not for me, for example.

Other rules are more important:

  *  use speaking names

  *  ensure that a unit (e.g. a function definition) can been seen in its
 whole

  *  carefully document complex operations

  *  combine a general overview with detailed source documentation.



-- 
Dieter
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Philipp von Weitershausen

On 24 Aug 2007, at 19:27 , Dieter Maurer wrote:

Philipp von Weitershausen wrote at 2007-8-24 15:34 +0200:

...
This and other aspects are things I don't particularly love about
PEP8 either, but I value consistency over my personal preferences.


I do honor other people's
decisions though, and would always follow the original author's  
style.

Consistency is better than correctness in this case. (I usually
tend to value
correctness higher than consistency.)


Well, this may sound harsh, but I see some appeal in actually forcing
a particular coding-style on everybody. It's soo late for anything
that has been started already, but I don't see a reason why we simply
can't say:

  If you start a new project on svn.zope.org, it'll have to be in
PEP8 styling.

The rule being behind this (as already mentioned above), that
consistency values higher than personal preferences.


Sure, you can say it...
But, you will loose some packages...

I find it very stupid to prescribe whilespace rules and
'_' separation versus camelCase spelling.


I wonder how you can like this language with significant whitespaces  
and lots of underscore rules then :).


In any way, this is a guide, not law. I can't and won't force you to  
adhere to the style guide. But I'll nag you and other people will  
surely find it difficult working with inconsistenly style code. (I,  
for one, find the ZODB externals *extremely* difficult to work with  
for total lack of naming conventions).

___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Philipp von Weitershausen

On 24 Aug 2007, at 18:55 , Fred Drake wrote:

On 8/24/07, Stephan Richter [EMAIL PROTECTED] wrote:
That's not harsh. That's the point of a coding style. :-) The long- 
term

benefits are greater.


Agreed!


Ok, then we're on the same page.

But if you prefer consistency, then we really should be staying  
with the Zope

3 style guide,


This, of course, all depends on the answer to the question:
Consistency with what?  Zope 3 history?  The larger Python community?
(Don't think the world agrees on PEP 8...)


This is a good question. The world may not agree on PEP8, but it  
seems to be predominant in the more recent code that I've encountered  
so far, such as Paste.



which is effectively PEP 8 with camel case methods, functions
and attributes. Also, the Zope 3 style guide does more than PEP 8  
as it
discusses other files and package structure as well. So, maybe we  
should
write another official ZF document with our style guide capturing  
the result

of this discussion.


Maybe.


I'd like to avoid creating our own processes as much as possible if  
we can, hence my suggestion to use PEP8.  Stephan is probably  
referring to http://wiki.zope.org/zope3/CodingStyle. It seems  
horribly outdated in some areas. It does cover more than PEP8,  
though. Perhaps the differences to PEP8 should finds its way into my  
guide.


That said, I guess I could retrieve from one style for a  
namespace in the
interest of keeping z3c open for all to contribute to. But I  
certainly would
not switch to PEP8; we worked too hard to make the original Zope 3  
tree Zope


What bugs me most is that changing the style used keeps coming up;
it's silly to keep trying to change it.  *That* is what defeats the
benefits of having one to start with.


Absolutely.


I don't really care whether the style is the classic Zope 3 style or
PEP 8, as long as it never changes.


With this you seem to suggest we should continue using the classic  
Zope 3 style.



I don't really care about the decision we end up with. My goals are:

* to have as little process and documentation to maintain for  
ourselves as possible,


* be mainstream, in other words close enough to everybody so that  
the sacrifices everybody has to make are small compared to the benefits,


* share the same ideas with other projects that are close to us  
(twisted, Paste, etc.) because we will potentially use their stuff  
and they will potentially use our stuff.


One way or another, I was bound to run into resistance with whatever  
choice I made in the guide. I'll be happy to change the guide if this  
list can somehow come to a verdict on which style guide is preferred  
or if I receive a Papal edict (which I would save us a great deal of  
typewriter ink :))


___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Philipp von Weitershausen

On 24 Aug 2007, at 19:55 , Dieter Maurer wrote:

Andreas Jung wrote at 2007-8-24 19:35 +0200:

...
Whitespace rules have a major impact on the readability of code.
Readability is a major point when we talk of code quality.  
Readable code

does not make code automatically but good code has to be readable.


Lots of whitespace does not make the code more readable for all
persons -- it does not for me, for example.

Other rules are more important:

  *  use speaking names

  *  ensure that a unit (e.g. a function definition) can been  
seen in its

 whole

  *  carefully document complex operations

  *  combine a general overview with detailed source documentation.


These are all excellent points. THat doesn't mean that the right  
usage of whitespace can't make code more readable.



Anyway, I think this will be my last response on the style guide  
issue because we all are mostly on the same page, and we're we not  
it's a matter of taste and that's hard to argue about.


___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Fred Drake
On 8/24/07, Philipp von Weitershausen [EMAIL PROTECTED] wrote:
 it's a matter of taste and that's hard to argue about.

No, that's easy to argue about, it's just not productive.  That's the
problem.  :-)


  -Fred

-- 
Fred L. Drake, Jr.fdrake at gmail.com
Chaos is the score upon which reality is written. --Henry Miller
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-24 Thread Andreas Jung



--On 24. August 2007 19:55:35 +0200 Dieter Maurer [EMAIL PROTECTED] 
wrote:



Andreas Jung wrote at 2007-8-24 19:35 +0200:

...
Whitespace rules have a major impact on the readability of code.
Readability is a major point when we talk of code quality. Readable code
does not make code automatically but good code has to be readable.


Lots of whitespace does not make the code more readable for all
persons -- it does not for me, for example.

Other rules are more important:

  *  use speaking names

  *  ensure that a unit (e.g. a function definition) can been seen in
its  whole

  *  carefully document complex operations

  *  combine a general overview with detailed source documentation.


ACK on everything of that. But reading code comes before understanding code.
And the visual impression of code has a strong impact on how we read code 
and on how we understand code. Rules (written or unwritten) exist to 
organize a certain aspect in life, work etc. Rules are (usually) made to 
satisfy the needs of a majority. If we organize code in a common repository 
then the code styles  (or call them rules) tell the individual programmer 
how most programmers would expect how good code should like. When we write 
code and check it into a public repository the code was written to solve a 
particular problem but it has to follow the most basic rules that are set 
by the developers community as a whole. There is always place for personal 
preferences however there is some border..


Bringing it back to the point: Understanding matters, reading comes before 
understanding so rules about whitespaces, # of statements per line etc.

really matters.

-aj

pgplqywBcAgHk.pgp
Description: PGP signature
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com



Re: [Zope3-dev] RFC: Guide for maintaining software in the Zope repository

2007-08-23 Thread Andreas Jung



--On 24. August 2007 02:37:01 +0200 Philipp von Weitershausen 
[EMAIL PROTECTED] wrote:





http://svn.zope.org/*checkout*/Sandbox/philikon/foundation/maintaining-so
ftware.txt



Thanks for writing this excellent guide. However I am personally unclear
about specifying the dependencies and their version requirements (but this 
is more a setuptools issue than a Z3 specific one).


Andreas


pgpDOZIoeKX0u.pgp
Description: PGP signature
___
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com