acmeattic-devel team mailing list archive

[Aditya Manthramurthy <aditya.mmy@xxxxxxxxx>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Thursday 15 July 2010 12:29 AM, Karthik Swaminathan Nagaraj wrote:
> Hi,
>     Given that this is the first time I am involving myself in a serious
> project, here are some questions I had. It also feels better to put it down
> in a doc.
> 
>    - *Coding style:* Do you use a known standard for formatting code? Could
>    you pass on a link to the same. I found these:
> Google<http://google-styleguide.googlecode.com/svn/trunk/pyguide.html>,
>    PEP8 <http://www.python.org/dev/peps/pep-0008/>

I think the best is to use PEP 8 [1] for coding style conventions and
PEP 257 [2] for docstrings conventions. The google standard seems to be
a superset of PEP 8, and has very detailed instructions. It would be a
pain to follow all of them carefully. PEP 8 is good enough for the
standard python libraries, and so should be good enough for us.

[1]: http://www.python.org/dev/peps/pep-0008/
[2]: http://www.python.org/dev/peps/pep-0257/


>    - *Code reviews:* I advocate the following:
>       - Any code *has* to be reviewed by someone else before Commit. (OFC
>       all of us are committers). Maybe two reviews in the early stages?
>       - Coding style is enforced at this stage
>       - Techniques used are reviewed

I think a single review by a member of the acmeattic-devel is enough.
Trivial bugs should be caught here. When bugs arise, the people who
implemented/reviewed the feature, have a priority to fix that bug,
failing which anyone else can fix it.


>    - *Unit testing:* Though this is really painful, it would be really great
>    to have parts of code that is known to work error-free.
>       - I would advocate this right from the first, though it may increase
>       the dev time (at least for the important modules)
>       - Is there a way to run a check on Python code (similar to
>       compilation) to clean syntax bugs? Otherwise, unit tests assert
> this esp in
>       Python

I don't know much about how unit testing would be written for modules
that have certain types of dependencies - for example, a function may do
something if a certain situation occurs in a database, or some sort of
network communication is received. These are all state-change kind of
functions. Writing a unit test for them would involve first creating the
conditions for that that function to work properly. It may not be
possible to do this, without specialised test cases. Can someone more
knowledgeable about this explain?

To compile python files, without executing them, there is a command
"py_compilefiles" which tries to form the byte-compiled versions of the
files (.pyc). This will do syntax checking, and we can use it.

>    - *Documentation:* Document your Classes, methods and variables during
>    implementation. A little extra documentation never hurt anyone.
>       - The Wiki usually captures the high level documentation and does not
>       contain implementation details
>       - Some of us might think of magic hacks that work - lets enlighten
>       others how that works!

See PEP 257 about docstrings. We should consider it a priority to write
docstrings and keep them updated the code changes. For software
documentation, we should consider using sphinx [3]. It is the technology
used to generated sexy looking documentation like at http://docs.python.org

[3]: http://sphinx.pocoo.org/

> 
> Is there anything that I've missed?
>

How should we organise development itself?

My answer is to organise a series on lp. Say the 0 series - this
represents releases of the s/w that have version numbers like 0.1, 0.2,
etc.

Development happens in a pre-planned way. We target bugs/blueprints to
the next minor version of the software (say 0.1 is stubs, we then map
the blueprints/bugs for getting to 0.2), and developers can pick up one
of these targets (bugs/blueprints) and develop them on their own. Review
happens by another member of the devel team, and then committed to trunk.

When we have enough new features to create a stable release, before we
create it, we do lots of testing, creating alpha, beta releases, and
then we create the stable release and publish packages for it. When a
new phase of development starts, like say we decide to rewrite the
encryption system (for whatever reason), we can start a new series like
series 1.x, 2.x, etc. How does this sound?

If this sounds good, over this weekend (as PK and me are planning to
meet), PK and me will write simple stubs to start of the coding. The
stubs will contain names for classes or any such thing. It is just
planned to write simple command parsing code, etc, which are necessary
even in the earliest version of the s/w. We will call this version 0.1.
Of course, it can be mercilessly edited by others who are working on
specific featurs later on :-)

In the meanwhile, it will be good to decide what features to include in
stable release 1! There is feature release schedule at [4]. We should
edit that to get an overview of features in future releases. Once that
is ready, we can write specific blueprints for minor releases, and begin
coding intensively!

- --
Aditya.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)

iQIcBAEBAgAGBQJMPtHlAAoJEJp+wO5X65iG9LoQAJ/BurIqR2p1+Z56awFuGwZr
XYM+8w0m0yuj59XIdVdWGMdOgmd9lLM3Xq5FEi2P+j7EaitlBq3D+vlCy1OEwL5e
qFNbGJ0eFwZh7nQJY8tsPB1p+UI+ZjqlIjBl1Y4bIUIuQwxjHkPYpjn1Ujcp2r/E
NeHx82Tz4TZoT1u+JJjZ9H3qyVYWSjYG1FrqRb2lBTTsFH6PtfAJVD7P223pOChz
cJOrMI4XLeSDx/j5r7p6KPFAsZDXxK+fxWL1TDn3LBXMzXwgeOcvnDb9wX0GUyOF
p9QNg1jcTZ0U/KcPEk5wGzucvJO2ZquW4lzEL6oocZq/VxiRvfcoz6rSvy7W3i4B
GT6Y8TCYOuuXYTWgxz7uHFnemMXaaz6PTQlo1c4wFz877oDVdxjcBP5VpilR3kYh
MWWABEzlA4R4mrHNCjkYYdj1aZJAYN8cybB9eP2Bnnv/nvkT0oGkei4PYiPvmCgQ
41ML5dHHHD24vuBBZ2UmGfgeIy+y2bL9R3T7FAm66e8kWa2sGBWmm0wNokXzw9vR
iWDFdQ9TbjQcJ5pMRuO06XHswunHGe/gZ2adOmu1bqTfVh/CmIRMn7DVhE2PcYEY
29ZJcdgnTl+C5hZ9BdMWWD908bu5k/iZXYjZbXSoPOWWNTmAoO3ZjpDbLjxQNMJI
4fTRt8cJj4HusRMiRHqS
=/Pr3
-----END PGP SIGNATURE-----