| | 1 | = Procyon coding standard = |
| | 2 | |
| | 3 | Procyon adheres closely to [http://divmod.org/trac/wiki/CodingStandard the Divmod coding standard] |
| | 4 | (which in turn builds on the Twisted coding standard.) There are however some deviations: |
| | 5 | |
| | 6 | * One (1) line between methods and closely related code (`registerAdapter` or `registerUpgrader` |
| | 7 | after a class definition, for example.) |
| | 8 | * Two (2) lines between classes, import statements and generally code that has little or no relation |
| | 9 | to the proceeding code. |
| | 10 | |
| | 11 | To reiterate some key points from the aforementioned coding standards: |
| | 12 | |
| | 13 | * Lines are flowed at 79 columns, more or less. Don't sacrifice readability for newlines, use common |
| | 14 | sense. |
| | 15 | * Doc-strings are extremely important and need to follow some guidelines: |
| | 16 | * Doc-strings should be clear in the information they are attempting to convey, but not overly verbose, |
| | 17 | properly punctuated and written in plain English. |
| | 18 | * Use [http://epydoc.sourceforge.net/epytext.html Epytext markup] to properly document attributes, |
| | 19 | parameters, exceptions and so forth. |
| | 20 | * The first line of the doc-string should be a brief (not passing the 79 column mark, if at all possible) |
| | 21 | description of the thing it is describing. Optionally, next paragraph should then go into more detail |
| | 22 | and finally followed by parameters (type, then parameter) then exceptions (if any) and finally the return |
| | 23 | type (if any.) |
| | 24 | * Use a doc-string (following the above rules) for modules when the behaviour is well-contained, not entirely |
| | 25 | obvious and there is a need for an example. (See [source:trunk/procyon/api/tvdb.py] for an example.) |
| | 26 | * Comment any quirky or unclear behaviour with a concise comment. |
| | 27 | |
| | 28 | In general, the existing codebase should be used as a guide on how to layout a particular piece of code. |
| | 29 | |
| | 30 | Do '''not''' submit (or commit) patches for largely undocumented code... ever. |
