Ok now. As I am a complete lamer when it comes to team coding, coding
standards etc., I'll take your words for it, but have nonetheless several
lame questions.
The purpose of the rewrite was
a) to restructure the framework
> b) to have consistent formatting and documentation
> c) to move to the API
> and possibly
> d) to add i18n support
> First of all: point b.
> Before any new code is written, we should agree on a fixed coding style.
> The current framework has several coding styles used throughout the
framework - and even sometimes in one class: in the Page class, we have
got Page.urlname, Page.isAutoTitle and
Page.put_async... - I think we
should use one style for the entire framework.
If team coding is a democracy then I vote for
camelCaseWithFirstWordLowercase.
It's a strong standard in Java (which is a close cousin to Python) and is
frequent in Python too (take Twisted for an example).
For the coding style, I propose the following:
* As base: PEP 8 [1].
Fine. I suggest the most common 1 indentation level = 4 spaces.
* UTF8 encoding for all files (and using u'' for all strings), with UTF8 BOM
I'll assume gvim does that for me. o_O
* Docstrings mandatory, using Epydoc [2] for describing parameters and
return value. Defining the function in this way
almost automatically
defines unit tests for that function.
That's an interesting document - smells of javadoc too. :)
One module per class
Java style again? ;)
Anyway, let's make sure I understand a "module" correctly, especially in
the
context of unit tests later on.
A module corresponds to one .py file (like http.py or api.py from our
example) and a folder of these (data/) is a package, not module? Despite of
this:
>> import data
>> data
<module 'data' from 'data/__init__.py'
Note that all code should be written thread safe: we want to use
persistent HTTP connections and this means we will be
sharing a connection
throughout several page objects. If we want to be able to put in a thread,
we really need to make sure code is thread safe.
If I may suggest, let's leave data.http.HTTP (or its equivalent) as an
object encapsulating a connection and presenting wrappers on GET and POST
methods, but in a non-thread-safe manner and instead resolve this at a
higher level (Site, perhaps) by keeping a pool of connections or something
similar (or maybe write a special HTTPPool handler between Site and HTTP).
That's really a matter of deciding whether the framework handles
multithreading or do we tell people that each thread should have its own
instance of Site.
Secondly: point a.
> <snip
Because adding structure afterwards is much harder, I think we first
should decide on what modules/classes we want,
then defining what
functions we want and what these functions should do.
After that, we can
start writing unit tests and functions.
Where do we start? Edit
http://www.botwiki.sno.cc/wiki/Rewrite and add
classes until someone says enough?
On a compatibility note; even though we are changing the way the framework
works, it should be possible to create a layer that
maps functions in the
old framework to the new framework.
Yes, I would assume most methods of current high-level objects (Page, Site,
generators) will not change their interface much.
thirdly: point c.
Yes, <3 API - I think we established that already. :
finally: point d.
This is not a very important point, but it's kinda interesting. With the
new framework, it's easier to restructure existing functions, making
translations easier.
Ok now, can you elaborate on this? I don't think I'm getting the point - we
already same i18n - bots have localized edit summaries, the framework knows
#REDIRECT and namespace names locales as well.
Are you talking about some whole new level of i18n?
I'm sorry for the long email, and I repeat: I really appreciate your
efforts, but I really think we should address these
issues before starting
at - even the most basic - code.
Well, it seems I'm a coder, not project designer and it tempts me to stand
back, watch the fireworks and return when we actually need some code. But
instead, I hope to gain some experience in team programming.
Misza