projects.quakecon.org

Conventions ===========

.. contents::
:local:
:backlinks: top

Design Conventions

---

To integrate our look-and-feel across multiple projects, we have design conventions that should be followed:

Branding
_~~~~~~

This branding guidelines document serves as the fundamental guide for QuakeCon branded materials.

• QC_styleguide_362009.pdf

Repository Conventions

---

Structure
_~~~~~~~

The structure of our repository follows the very standard convention of ``trunk``, ``branches``, and ``tags``. In addition, the trunk may branch additionally to house multiple interrelated projects. For example:

• ``trunk``
  • ``qcauth`` - the qcauth mainline
  • ``qcauth_keygen`` - the qcauth_keygen mainline
  • ``nightly`` - the mainline for the nightly maintenance scripts
• ``branches``
  • ``dothings-42`` - a branch for ticket #42 from trunk/qcauth
  • ``do_different_things-57`` - branch for ticket #57, maybe from trunk/qcauth_keygen
• ``tags``
  • ``qcauth-beta1`` - a tagged version of qcauth, frozen for beta

``trunk``
_~~~~~~~

``trunk`` conventions are relatively clear cut:

• Must always remain functional
• All tests must always pass
• Code should be reviewed.

``branches``
_~~~~~~~~~~

This means that almost all "work" should be done in feature branches. Feature branches:

• Should be named with an arbitrary "short name" and a ticket number, separated by a space.
• Should be branched from a specific project trunk, not the entire ``trunk``. (Unless of course the changes effect multiple project, then branching the entire ``trunk`` is great.)
• Can be in any state of function, used in any fashion which helps the developer get their work done.

Good example branch names include: ``editgroup-432``, ``devtools-123``, ``nightly-5683``, ``cleanup_devtools-131``. Use of underscores is fine if it increases readability, but not required. The bug number should always be included preceded with a hyphen. Whitespace in branch names would be considered bad form.

For guidance in with merges see Managing Branches.

``tags``
_~~~~~~

Tags will be handedly primarily by the maintainer of the projects. They are "code freezes" for testing, production, or other release.

Managing Branches
_~~~~~~~~~~~~~~~

Managing branches can be a challenging task using subversion. Definitely use the Managing Branches guide constantly as you wrangle packages into shape.

Code Conventions

---

XHTML
_~~~

CSS
~~~

• Opening braces on the same line as the element selector.
• One attribute per line, one tab (2 spaces) in from selector.
• Left align attributes and their values separately.
• Order attributes in logical groups.

.. sourcecode:: css

div ul.user_list {

  padding:          4px 8px 4px 8px;

  border:           2px solid black;

  font-weight:      bold;

  font-size:        1.5em;

  list-style-type:  none;

}

JavaScript
_~~~~~~~~

https://developer.mozilla.org/en/JavaScript_style_guide

Python
_~~~~

Our Python coding guidelines are best summed up as `PEP 8`_. Additional code conventions follow.

.. _PEP 8: http://www.python.org/dev/peps/pep-0008

Docstrings and Comments
_~~~~~~~~~~~~~~~~~~~~~

reStructuredText and Sphinx
```````````````````````````

All ``docstring`` are reStructuredText_. Consult the `Quick Reference`_ or the `Cheat Sheet`_ for quick guidance on formatting.

.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Quick Reference: http://docutils.sourceforge.net/docs/user/rst/quickref.html
.. _Cheat Sheet: http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt

As Sphinx_ is used to generated all of the direct documentation for QuakeCon projects, the extensions to reStructuredText are appropriate for annotating documentation with significant syntactical or semantic information. You can find those extensions to reStructuredText in the `Sphinx documentation on the topic`__.

.. _Sphinx: http://sphinx.pocoo.org/
_ Sphinx

Here's an example of an ``docstring`` that uses both reStructuredText and the Sphinx extensions:

.. sourcecode:: python

def user_associate(self, app_name, app_key, username):

    """Get the unique identifier for a :class:`qcauth.model.identity.User`.

:param app_name: application account name
:param app_key: application account key
:param username: handle to fetch key for
:return: the corresponding user key
:return type: string
"""

1. do things

Single line and multi-line docstrings
`````````````````````````````````````

Due to the manner that automated tools handle ``docstrings``, please ensure that the very first syntactic line of your ``docstring`` always contains a concise summary of your unit of code. Single line strings are more desirable than multi-line strings when the ``docstring`` is only a single line.

Examples:

.. sourcecode:: python

def example_method(self):

    "An example method to demonstrate a solid, one-line comment." 

    pass

.. sourcecode:: python

def example_function(p):

    """An example function to demonstrate a solid, multi-line comment.

While this function doesn't actually do anything, it's useful to show this comment style.

:param p: parameter to be returned

:returns: whatever was passed in as p

""" 

return p