Changes between Version 23 and Version 24 of TracDev/CodingStyle
- Timestamp:
- Jan 14, 2015, 10:11:44 PM (9 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
TracDev/CodingStyle
v23 v24 1 = Trac Coding Style =1 = Trac Coding Style 2 2 3 Executive summary: we'll usually frown on patches that 3 Code is read more often than it is written, so we adhere to a coding style. Patches that: 4 4 - have long lines 5 5 - have multiple statements per line 6 6 - break the naming conventions 7 because this immediately tells us the patch author hasn't tried to follow our coding conventions. On the other hand, a patch that follows the conventions detailed below tells us that the patch author has made some effort, therefore the patch itself is much more likely to be a [[TracDev/SubmittingPatches#Whatisagoodpatch|good patch]] and has a better chance to get the attention it deserves...7 do not follow our coding style. On the other hand, a patch that does meet the conventions is much more likely to be a [[TracDev/SubmittingPatches#Whatisagoodpatch|good patch]] and has a better chance to get the attention it deserves. 8 8 9 Like most Python projects, we adhere to [pep:0008 PEP 8 (Style Guide for Python Code)] and [pep:0257 PEP 257 (Docstring Conventions)]. Be sure to read those documents if you intend to contribute code to Trac. 9 10 10 Like most Python projects, we try to adhere to [pep:0008 PEP 8 (Style Guide for Python Code)] and [pep:0257 PEP 257 (Docstring Conventions)]. Be sure to read those documents if you intend to contribute code to Trac.11 Note that some of the current Trac code could violate coding style rules. We are always in the process of refactoring the offending modules so that all code adheres to the conventions. 11 12 12 Note that some of the current Trac code could violate a couple of the rules stated below. We are always in the process of refactoring the offending modules so that all code uses the same conventions, though it's much better now than it used to be. 13 14 == Naming conventions == 13 == Naming conventions 15 14 16 15 * Package and module names should be all lower-case, words ''may'' be separated by underscores. … … 22 21 * Abstract base classes should use the suffix `Base`. 23 22 24 == Strings ==23 == Strings 25 24 26 25 - Use `"..."` for text meant to be read by users, … … 33 32 - For SQL code, use multiline `"""..."""` strings if needed. Single line SQL also use `"..."` style most of the time, as they often contain single quotes (`'`). 34 33 35 == Miscellaneous ==34 == Miscellaneous 36 35 * '''Lines shouldn't exceed a length of 79 characters.''' [[br]] 37 No, it's not because we're mainlyusing VT100 terminals while developing Trac,36 No, it's not because we're using VT100 terminals while developing Trac, 38 37 rather because the diffs look nicer on short lines, especially in side-by-side mode. 39 38 * ''Never'' use multiple statements on the same line, e.g. `if check: a = 0`. … … 41 40 * Use `raise TracError("message")` instead of `raise TracError, "message"` 42 41 * Only use a `global` declaration in a function if that function actually modifies a global variable. 43 * A little d ifferencefrom PEP:0257: we usually don't ''insert a blank line between the last paragraph in a multi-line docstring and its closing quotes''.42 * A little deviation from PEP:0257: we usually don't ''insert a blank line between the last paragraph in a multi-line docstring and its closing quotes''. 44 43 * docstrings should contain reStructuredText markup, as understood by [http://sphinx.pocoo.org Sphinx], as we're using the latter for generating our ApiDocs. \\ 45 44 In some situations however, like for documenting Macros and Options, WikiFormatting … … 48 47 macros, respectively. 49 48 * Prefer tuples without parenthesis, particularly in `return` and `yield` statements. When parenthesis are needed for line continuation they can be used rather than a backslash on the continuation line. 49 * Code blocks are copiously documented, describing the code blocks' functionality concisely. 50 50 51 == JavaScript == 51 == JavaScript 52 52 53 !JavaScript code should follow [http://javascript.crockford.com/code.html these conventions] with the following exceptions and additions: 53 54 * Lines shouldn't exceed a length of 79 characters. … … 57 58 * Define non-anonymous functions as `function fooBar() {...}` (rather than `var fooBar = function() {...}`) 58 59 * Keep as much as possible private, by defining private functions in an inner scope. Attach functions you want to export to the $ symbol. 59 * Use a `trac-` prefix for all id and class names. (For new names. Changing old names would break customizations.)60 * Use a `trac-` prefix for all id and class names. This is for new names, because changing old names would break customizations. 60 61 * Prefix variables containing a jQuery object with `$`. 61 62
