source: HACKING @ 1589:678869140388

Revision 1589:678869140388, 2.8 KB checked in by Arc Riley <arcriley@…>, 7 years ago (diff)

Updated HACKING for PEP-8 code style (and post-pyrex)

Line 
1PySoy Hacking Guidelines
2========================
3or, how to contribute code that doesn't suck
4--------------------------------------------
5
6Introduction
7~~~~~~~~~~~~
8As a free software community project PySoy is worked on by a large number of
9users.  Each of these users have their own preferences for code layout and
10with their own unique styles.  Without some structure applied to this process
11the project would devolve into an unparsable, unmaintainable mess.
12
13We also benefit a great deal from developers working from "different angles".
14A problem addressed with one solution may be very difficult, while by another
15method very easy.  Guidelines set too strictly would thus dampen the beautiful
16dissonance that makes our community so strong.
17
18So in an attempted balance these guidelines are set forth.  Use them when it
19makes sense to, bend or break them when nessesary, and don't complain if
20someone cleans your code up to better meet these guidelines. :-)
21
22
23Code Layout
24~~~~~~~~~~~
25
26Use PEP-8 (http://www.python.org/dev/peps/pep-0008/) as much as possible.  In
27summary:
28
29 * Lines should wrap at 79 characters
30
31 * 4 space indententation
32
33 * Where PEP-8 can't apply (ie, C code) try to be as clean as possible
34 
35 
36Label Conventions
37~~~~~~~~~~~~~~~~~
38
39 * Modules should be all lowercase
40
41 * Classes should be CamelCase
42
43 * Methods and properties should be with lowercase
44
45   - ie, "forces.MonoPole.strength"
46
47 * Avoid functions outside of a class in the public API
48
49
50Module Layout
51~~~~~~~~~~~~~
52
53 * Modules should contain many classes
54
55   - consider merging with another module if only one or two classes
56
57 * Each class should exist in it's own .gs or .c file
58
59   - it's much easier to track API changes and navigate code this way
60
61   - temporary "testing" classes are an exception to this
62
63 * Modules should often be named plural with base class the singular
64
65   - ie, soy.bodies.Body, soy.widgets.Widget, soy.joints.Joint
66
67 * Modules must begin with pydoc strings
68
69   - begin with standard multiline pydoc help for the module
70
71   - include AGPLv3 license information in __credits__
72
73   - __author__ should contain the module's current maintainer
74
75   - __version__ string should be $Rev:$ so users can find code revisions
76
77
78Class Layout
79~~~~~~~~~~~~
80
81 * Dimensions and ranges should be combined into a single property
82
83   - reduces code and API complexity
84
85   - ie, Body.position, not Body.x Body.y Body.z
86
87   - ie, Joint.stops, not Joint.lostop Joint.histop
88
89 * Classes should accept common properties as __new__/__init__ kw's
90
91   - ie, soy.widgets.Projector(scene, camera=cam, position=(0,25))
92
93 * Every class and every property MUST be documented
94
95   - this is done with a multiline string directly in the code
96
97   - pydocs are copied to both .c and compiled modules, comments are not
98
99
100Documentation
101~~~~~~~~~~~~~
102TODO, see above for now
Note: See TracBrowser for help on using the repository browser.