[Pyogp] Design and Coding Process

[Christian Scholz]

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

[Locklainn]

I like this proposal. We were talking and had realized that we were not
collectively making design decisions. We DO make overall architectural
decisions, but the design aspect got left out. We seem to take the "GET
IT DONE" design process. We were talking about having some way to make
sure our design is sound before we just bust in and start coding. This
isn't to say to use the waterfall method. We should most certainly do
some iterations of the design. It is more or less making ourselves more
aware of needing to assist each other in a design before we each
independently start coding what we want to code.

I think this is a great proposal. I would also like to add that we need
a way to determine what decisions need the round table for design. Right
now, it seems the round table is used for architectural dependencies
only. Is this the level we want to keep or should we all be discussing
more detailed decisions, like how a component might be coded.

Thanks Christian!
TJ

Post by Christian Scholz
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.
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.
- 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

[Dirk Krause]

Hi,

I'd like to chime in into supporting this proposal.

Regarding the question on how much detailed the discussion should get, I'd say as detailed as it can get? What I feel is that in the big three pyogp meetings not everyone is on Tao's level (well, I am certainly not, though gaining ground), esp. regarding experiences with existing code bases. I hope this gets handled with point 3 and 4 of the list.

One thing that I'd like to discuss is some sort of peer programming, like having pairs of developers collaborating on specific problems. While I have no idea yet on how to handle that technically in an intercontinental way (some VNCserver looking-over-the-shoulder-approch we use here might raise security issues), I could imagine that this gives valuable output and esp. two people building up know-how on the same issue. This way someone could be off for a time and still there is someone else able to answer questions.

Best Regards,
Dirk/Bartholomew



-----Urspr?ngliche Nachricht-----
Von: pyogp-***@lists.secondlife.com [mailto:pyogp-***@lists.secondlife.com] Im Auftrag von Locklainn
Gesendet: Dienstag, 5. August 2008 15:28
An: ***@lists.secondlife.com
Betreff: Re: [Pyogp] Design and Coding Process [bayes]

I like this proposal. We were talking and had realized that we were not
collectively making design decisions. We DO make overall architectural
decisions, but the design aspect got left out. We seem to take the "GET
IT DONE" design process. We were talking about having some way to make
sure our design is sound before we just bust in and start coding. This
isn't to say to use the waterfall method. We should most certainly do
some iterations of the design. It is more or less making ourselves more
aware of needing to assist each other in a design before we each
independently start coding what we want to code.

I think this is a great proposal. I would also like to add that we need
a way to determine what decisions need the round table for design. Right
now, it seems the round table is used for architectural dependencies
only. Is this the level we want to keep or should we all be discussing
more detailed decisions, like how a component might be coded.

Thanks Christian!
TJ

Post by Christian Scholz
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.
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.
- 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

_______________________________________________
Click here to unsubscribe or manage your list subscription:
https://lists.secondlife.com/cgi-bin/mailman/listinfo/pyogp

[Christian Scholz]

Hi!

Post by Dirk Krause
I'd like to chime in into supporting this proposal.
Regarding the question on how much detailed the discussion should get, I'd say as detailed as it can get? What I feel is that in the big three pyogp meetings not everyone is on Tao's level (well, I am certainly not, though gaining ground), esp. regarding experiences with existing code bases. I hope this gets handled with point 3 and 4 of the list.

Well, 3 and 4 is in there because I also don't understand what exactly
the message system needs to do ;-) So it's not necessarily the Python
knowledge which is needed but the knowledge about the problem. And in
order to discuss a good solution everybody who wants to participate in
the discussion should understand the problem to some extent. Of course
the message system is probably also the most complex thing because of
all the encoding stuff etc. I guess when we come back to more
straightforward webservices then it should be easier.
(but then again there is this capabilities stuff which to many might be
obfuscated web services. So we maybe need to work on some good
explanation for this anyway as I guess every new project member will
have a problem understanding this concept).

Post by Dirk Krause
One thing that I'd like to discuss is some sort of peer programming, like having pairs of developers collaborating on specific problems. While I have no idea yet on how to handle that technically in an intercontinental way (some VNCserver looking-over-the-shoulder-approch we use here might raise security issues), I could imagine that this gives valuable output and esp. two people building up know-how on the same issue. This way someone could be off for a time and still there is someone else able to answer questions.

Yeah, some sort of sprint would be great. But as you said, the
decentralization might be a problem. That's why I wanted all those
Lindens (and others) to come to EuroPython in order to make some kickoff
meeting in person.

And you maybe just propose some time when you want to come to Aachen (or
I come over to Cologne) and we can make some sort of sprint.

cheers,

Christian

[Tess Chu]

Post by Dirk Krause
One thing that I'd like to discuss is some sort of peer programming, like having pairs of developers collaborating on specific problems. While I have no idea yet on how to handle that technically in an intercontinental way (some VNCserver looking-over-the-shoulder-approch we use here might raise security issues), I could imagine that this gives valuable output and esp. two people building up know-how on the same issue. This way someone could be off for a time and still there is someone else able to answer questions.

+1
In Icehouse, and now in Open Platform group, we find it very valuable to
pair program for these very reasons.

Post by Dirk Krause
Best Regards,
Dirk/Bartholomew
-----Urspr?ngliche Nachricht-----
Gesendet: Dienstag, 5. August 2008 15:28
Betreff: Re: [Pyogp] Design and Coding Process [bayes]
I like this proposal. We were talking and had realized that we were not
collectively making design decisions. We DO make overall architectural
decisions, but the design aspect got left out. We seem to take the "GET
IT DONE" design process. We were talking about having some way to make
sure our design is sound before we just bust in and start coding. This
isn't to say to use the waterfall method. We should most certainly do
some iterations of the design. It is more or less making ourselves more
aware of needing to assist each other in a design before we each
independently start coding what we want to code.
I think this is a great proposal. I would also like to add that we need
a way to determine what decisions need the round table for design. Right
now, it seems the round table is used for architectural dependencies
only. Is this the level we want to keep or should we all be discussing
more detailed decisions, like how a component might be coded.
Thanks Christian!
TJ

Post by Christian Scholz
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.
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.
- 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

_______________________________________________
https://lists.secondlife.com/cgi-bin/mailman/listinfo/pyogp
_______________________________________________
https://lists.secondlife.com/cgi-bin/mailman/listinfo/pyogp

[Enus Linden]

I wholeheartedly agree on all counts. Let's take my office hours on
Friday to come up with a strategy (reviewing Tao's proposal as a
starting point), and start looking at what's up next (that as yet
undefined roadmap).

Post by Tess Chu

Post by Dirk Krause
One thing that I'd like to discuss is some sort of peer programming,
like having pairs of developers collaborating on specific problems.
While I have no idea yet on how to handle that technically in an
intercontinental way (some VNCserver
looking-over-the-shoulder-approch we use here might raise security
issues), I could imagine that this gives valuable output and esp. two
people building up know-how on the same issue. This way someone could
be off for a time and still there is someone else able to answer
questions.

+1
In Icehouse, and now in Open Platform group, we find it very valuable
to pair program for these very reasons.

Post by Dirk Krause
Best Regards,
Dirk/Bartholomew
-----Urspr?ngliche Nachricht-----
Gesendet: Dienstag, 5. August 2008 15:28
Betreff: Re: [Pyogp] Design and Coding Process [bayes]
I like this proposal. We were talking and had realized that we were
not collectively making design decisions. We DO make overall
architectural decisions, but the design aspect got left out. We seem
to take the "GET IT DONE" design process. We were talking about
having some way to make sure our design is sound before we just bust
in and start coding. This isn't to say to use the waterfall method.
We should most certainly do some iterations of the design. It is more
or less making ourselves more aware of needing to assist each other
in a design before we each independently start coding what we want to
code.
I think this is a great proposal. I would also like to add that we
need a way to determine what decisions need the round table for
design. Right now, it seems the round table is used for architectural
dependencies only. Is this the level we want to keep or should we all
be discussing more detailed decisions, like how a component might be
coded.
Thanks Christian!
TJ

Post by Christian Scholz
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.
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.
- 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

_______________________________________________
https://lists.secondlife.com/cgi-bin/mailman/listinfo/pyogp
_______________________________________________
https://lists.secondlife.com/cgi-bin/mailman/listinfo/pyogp

_______________________________________________
https://lists.secondlife.com/cgi-bin/mailman/listinfo/pyogp

[Christian Scholz]

Hi!

Post by Locklainn
I like this proposal. We were talking and had realized that we were not
collectively making design decisions. We DO make overall architectural
decisions, but the design aspect got left out. We seem to take the "GET
IT DONE" design process. We were talking about having some way to make
sure our design is sound before we just bust in and start coding. This
isn't to say to use the waterfall method. We should most certainly do
some iterations of the design. It is more or less making ourselves more
aware of needing to assist each other in a design before we each
independently start coding what we want to code.

Glad you like it :-)

Probably there is no such thing as a design being finished ever (hence
those tests and everything to make refactoring possible) ;-) But I think
we are on the same page here.

As for the waterfall model it of course depends on the size of the
waterfall. We are not waiting until OGP is finished and then implement
the library but we do it in parallel. And the iteration in this proposal
is sort of in going from highlevel to lowlevel. There is of course also
no reason why somebody shouldn't tell the progress on the list or at
some huddle and get some feedback or so. Then this can also be an
iteration over this component and level.

Post by Locklainn
I think this is a great proposal. I would also like to add that we need
a way to determine what decisions need the round table for design. Right
now, it seems the round table is used for architectural dependencies
only. Is this the level we want to keep or should we all be discussing
more detailed decisions, like how a component might be coded.

I'd think the more comes over the mailing list the better and if there
comes up some point of deeper discussion we can do this in some
roundtable (what is the roundtable anyway? Enus' office hours? ). For
some bigger component or general direction we probably should discuss
this in a bigger round. Then the owner of the project (or maybe there
should be 2 co-owners for peer review?) can propose some solution. The
documentation part can of course also be done by a bigger group and the
brainstorming part on how to use it as well.

I think in general it would be good to post interface ideas always to
the list. So everybody knows what components are there and how to use them.

Thanks for your feedback!

-- Christian

Post by Locklainn

Post by Christian Scholz
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.
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.
- 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

_______________________________________________
https://lists.secondlife.com/cgi-bin/mailman/listinfo/pyogp