Hi there!
Locklainn and I had a little discussion yesterday about a process we
don't yet have, which is about how we do design discussions etc.
So in order to kickstart this I thought I come up with some proposal we
can start to discuss.
So here it goes:
1. Identify a problem to solve.
This should not be too difficult as we have many to solve ;-)
2. Identify what's blocking a solution
like before handling packets we might want to have some component
which receives them.
3. Understand and document the problem domain
In order to come up with a good design/architecture everybody should
at least roughly understand the problem. That means we need to work
through the specs (if they are available) or pressure people to make
them or walk through code and write it down ourselves.
As said, maybe we don't need to go down to the smallest bit here but
e.g. for event queue stuff it might mean having some documentation
what roughly happens with that queue. What is sent, what is received,
when, why, what are the special cases we need to take care of (in
case of UDP it might be retries, acks and such).
4. Optional: Play around with some rough code to show how it could work.
This might be very valuable as for many people (like me) it's then
easier to understand and could be run with debug prints etc. to see
what's happening. Sort of like the stuff in examples/
5. Identify the components
Based on the example script or the spec we might identify some
components which we can model then. In case of the Event Queue it
might be some Queue class. It also might need some communications
endpoint.
6. Write an example
As I like the top-down/test-driven approach I usually start with
some example on how I would use that component, e.g. by adding it
to some example code based on the library we already have.
This makes the interfaces clearer IMHO.
It can also directly be written as a doctest (login.txt was the
one I wrote for implementing the login procedure which meant
dissecting the example script and "cutting" it into components.
The good thing about a doctest is that it also can be tested.
7. Implement all the components used in the doctest and break them up
into smaller components again. Basically the same method could
apply, so you repeat 5,6,7 until the component is small enough and
e.g. a UDP socket. It depends on how much you want to have low level
components in the end in how much you cut them into pieces.
For login we e.g. have some high level API in api.py, some medium
level is what is used in api.py (Credentials, IPlaceAvatar etc.)
and lowlevel would be the actual capabilities implementation and
networking code.
Of course while you do 7 you should add tests as it fits. It makes
always sense to write them first and implement the code then. At least
for me it makes it clearer what I am actually trying to write.
In the 5-6-7 loop you could even implement some mockup code first which
simulates the expected behaviour of the more low level components. This
can later be used in the test itself as well and thus can stay in.
As for writing doctests first it might make sense for others to grasp at
the beginning what you are doing and how it can be used. They can even
start using it right away if some mockup code is in place.
Probably regular reports on the list on what one is doing is also good
but then again we have the huddles for this. It might make sense though
to share some code examples or example uses.
So much for my quick'n'dirty process proposal.
As for coding guidelines, I would like to add:
- Follow PEP-8 http://www.python.org/dev/peps/pep-0008/ at least for
naming things.
- add docstrings wherever possible
- add doctests inside docstrings where it makes sense (e.g. when some
method is a bit more complex and you want to show how to use it).
That's actually all what comes to mind right now.
Talk to you later!
-- Christian
--
Christian Scholz Homepage: http://comlounge.net
COM.lounge blog: http://mrtopf.de/blog
Luetticher Strasse 10 Skype: HerrTopf
52064 Aachen Video Blog: http://comlounge.tv
Tel: +49 241 400 730 0 E-Mail [EMAIL PROTECTED]
Fax: +49 241 979 00 850 IRC: MrTopf, Tao_T
neue Show: TOPFtäglich (http://mrtopf.de/blog/category/topf-taglich/)
_______________________________________________
Click here to unsubscribe or manage your list subscription:
https://lists.secondlife.com/cgi-bin/mailman/listinfo/pyogp
