acmeattic-devel team mailing list archive

[Aditya Manthramurthy <aditya.mmy@xxxxxxxxx>]

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

On Friday 16 July 2010 02:20 PM, suren 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/
>>>>
> 
> The reason I suggested Google was that it looked to cover almost all
> our points. I guess I can get a vimrc that will automatically take
> care of most stuff there.

What do you mean by "our points"? Are you sure you can find a vimrc to
check all the requirements in the google style guide? That style guide
is so severely detailed. Did you see what it says about list
comprehensions? Though it may be good advice, I do not want to code to
so restrictive a guideline. It is also difficult to enforce it, as there
are so many details to check on. What do others think?

For PEP 8 I found [1] that can automatically check for the most common
style guide errors, like spacing, blank lines, long lines, and various
other things. This could be a pre-commit hook too. Probably only
un-readable code needs to be caught during review (other than bugs, obv.).

[1]: http://pypi.python.org/pypi/pep8/


> 
>>>>
>>>>>    - *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.
>>>>
> 
> In the pairing up model I suggested,  Does it make sense the people in
> pairs review each others' code ?

I guess it would, but are we likely to pair up considering that many of
us may be geographically separated in the time to come? I think it would
make much better sense to plan for individual geographically distributed
coding in the long run.

> 
>>>> 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.
>>>>
> 
> This is nice. But this should be a pre-commit hook. I am assuming
> bazaar client has pre-commit hook model. Almost all version control
> systems I know have that. Not sure about Bazaar.

Bazaar Hooks:
http://doc.bazaar.canonical.com/bzr.dev/en/user-guide/hooks.html


> 
>>>>>    - *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/
>>>>
>>>>>
> http://www.stack.nl/~dimitri/doxygen/ - this is also popular. But does
> not give like pydoc though.

Sphinx is for hand written documentation - not really for pulling out
docstrings and creating documentation from that. doxygen and epydoc are
tools that can do that. I think we can use doxygen or epydoc to generate
documentation from source. But we probably have to write hand written
documentation as well right? For user guides, tutorials, etc. We can use
Sphinx for that.

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

iQIcBAEBAgAGBQJMQD2aAAoJEJp+wO5X65iGrEQP/jPMffe5j9B0cQQ3a6P6DjhV
oDaOD3lKUqGaBtP7FF+L/o9MSxcKak7yhaZVFJeMxzXWya5KTX1Vfqj4+SBWFmyu
0znBHlj1vMtEUYzPd/btsH18ev602bKyaUuzj8qwJpxwoh85qsy+s1NY5MmGHulr
8vy/vgqGOO3+VMIwLRtNJJfV48lHqXuowgFB7z/XCN3mCwS723UtcR5Zrxu0Du/M
1rGT8p2rt2l6RtKnBmZUHHF0O1oDx1f7DJzbRfr+XcYAmT11TW1Kn3YXg8fkrIMV
PD4o0+AW21EtLzczOydElzAwEA+czKccYSO0e8UXddUkmICIm76Yji93/uvh4HiK
jFgcMhTdr6c+3u6f5L2K8Rp4NOWsGlR9p8+7yH1gQcVYaSH8uGEPxrIac2GAP9HU
/xpP5LD5ZIXf5kr9m7C/yTTn03K1/vprudKRLB5Z2Swr0UEE+pTH0kN86dEdzbSD
pzTMZ8bGzCu2ZqqocZZ7gw78DbJaa83jy4J3FSgqQmLQtbNdqBBG2SehAnuG00xP
da/tl1DSo1U0S4158sMcRQ3qQ8eW15+ylNQ0JrAvsyMYHW/22eTFZRclbjWvn2Td
41Q6YgSnI9xLdx0kRoWuHn/HCTdLwtodL8QxELD4K0yKG9dEFQKxUnUzpieRGDkp
Rx6jTG6GlAYizYtVkPR0
=6/6D
-----END PGP SIGNATURE-----