= Trac Coding Style =

Executive summary: we'll usually frown on patches that 
 - have long lines
 - have multiple statements per line
 - break the naming conventions
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...


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.

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.

== Naming conventions ==

 * Package and module names should be all lower-case, words ''may'' be separated by underscores.
 * Class names use CamelCase [[br]] e.g. `TicketModule`
 * Class names inheriting from ''[TracDev/ComponentArchitecture#Declaringanextensionpoint trac.core.Interface]'' use mostly CamelCase, but are prefixed by an "I" letter [[br]] e.g. `ITimelineEventProvider`
 * The names of functions, variables and class members use all lower-case, with words separated by underscores [[br]] e.g. `do_delete`
 * Internal methods and variables are prefixed with a single underscore [[br]] 
   e.g. `_do_whatever_it_takes_to_delete`

== Strings ==

 - Use `"..."` for text meant to be read by users,
   use `'...'` for string constants (e.g. keys in dicts, CSS class names, filenames).
   The former strings will usually be translated, so be sure to play nice with the i18n conventions ([[TracL10N#ForDevelopers]]).
   In fact, the only "..." strings that won't get translated are the messages for the log.
   However this is not a very strict convention, rather a help to see what should be translated or not. It is OK to use `'...'` when the message contains `"` characters, for example, as such messages are often long and can't usually be mistaken for string constants anyway.
 - For regular expressions, use `r'...'` strings, 
   or multiline `r'''...'''` in `re.VERBOSE` mode.
 - For SQL code, use multiline `"""..."""` strings if needed. Single line SQL also use `"..."` style most of the time, as they often contain single quotes (`'`). 

== Miscellaneous ==
 * '''Lines shouldn't exceed a length of 79 characters.''' [[br]]
   No, it's not because we're mainly using VT100 terminals while developing Trac,
   rather because the diffs look nicer on short lines, especially in side-by-side mode.
 * ''Never'' use multiple statements on the same line, e.g. `if check: a = 0`. 
 * Prefer list comprehension to the built-in functions `filter()` and `map()` when appropriate.
 * Use `raise TracError("message")` instead of `raise TracError, "message"`
 * Only use a `global` declaration in a function if that function actually modifies a global variable.
 * A little difference from PEP:0257: we usually don't ''insert a blank line between the last paragraph in a multi-line docstring and its closing quotes''.
 * Also, in docstrings, we make quite a liberal usage of WikiFormatting. 
   This is even useful in some case, like for documenting Macros, as the
   macro classes docstrings are wiki-rendered when using the 
   [WikiMacros#AvailableMacros "[[MacroList]]"].

----
See also: TracDev