Permalink
Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
255 lines (156 sloc) 5.47 KB
How to Code
===========
In general, follow the languages established best practices, and fill
in the gaps where there are holes.
.. index:: code;guidelines
General Guidelines
------------------
* *Style matters*
How code is aligned matters, because code is reviewed, edited, and
public. Code that is uneasy to read does not align with the spirit
of open source.
* *Be consistent*
If you do something a certain way, be able to justify it. Don't mix
`camelCase` with `underscore_words` unless you have good reason.
* *Follow code around you*
If you don't know what you're doing try to follow what others have
done.
.. index:: code;testing
Testing
^^^^^^^
In languages and frameworks that provide easy test-ability, *write
tests!*
Go for 80% or more coverage, especially in the following areas:
* privacy - e.g. test that private things are private
* heavily used code - e.g. landing pages, library level code
* re-opened bugs
Tests last longer than code, as they tend to define the products'
functionality. They are valuable because they allow us to quickly
make changes without fear of hindering functionality.
The other half of testing is continuous integration. We should be
running our tests at every check in and be able to say with certainty
that the code is correct to the best of our knowledge. See
:ref:`ci-chapter`.
.. index:: code;python coding style
.. _python:
Python
------
We do what others in the python community have established:
* We follow PEP8_.
* We test using check.py_ which combines `pep8.py` and `pyflakes`.
* We follow Pocoo_'s extensions of PEP8_ as they are well thought out.
Import Statements
^^^^^^^^^^^^^^^^^
We expand on PEP8_'s suggestions for import statements. These greatly improve
ones ability to ascertain what is and isn't available in a given file.
Import one module per import statement::
import os
import sys
not::
import os, sys
Separate imports into groups with a line of whitespace:
standard library; Django (or framework); third-party; and local imports::
import os
import sys
from django.conf import settings
import pyquery
from myapp import models, views
Alphabetize your imports, it will make your code easier to scan. See how terrible this is::
import cows
import kittens
import bears
A simple sort::
import bears
import cows
import kittens
Imports on top, ``from``-imports below::
import x
import y
import z
from bears import pandas
from xylophone import bar
from zoos import lions
That's loads easier to read than::
from bears import pandas
import x
from xylophone import bar
import y
import z
from zoos import lions
Lastly, when importing things into your namespace from a package use an alphabetized
``CONSTANT``, ``Class``, ``var`` order::
from models import DATE, TIME, Dog, Kitteh, upload_pets
If possible though, it may be easier to import the entire package, especially for methods
as it help answers the question, "where did ``you`` come from?"
Bad::
from foo import you
def my_code():
you() # wait, is this defined in this file?
Good::
import foo
def my_code():
foo.you() # oh you...
Whitespace matters
^^^^^^^^^^^^^^^^^^
* Use 4 spaces, not 2---it increases legibility considerably.
* Never use tabs---history has shown that we cannot handle them.
Use single quotes unless double (or triple) quotes would be an improvement::
'this is good'
'this\'s bad'
"this's good"
"this is inconsistent, but ok"
"""this's sometimes "necessary"."""
'''nobody really does this'''
.. _PEP8: http://www.python.org/dev/peps/pep-0008/
.. _check.py: https://github.com/jbalogh/check
.. _Pocoo: http://www.pocoo.org/internal/styleguide/
.. index:: code;django coding style
Django
------
Follow :ref:`python`. There are a few things in Django that will make
your life easier:
Use ``resolve('myurl')`` and ``{{ url('myurl') }}`` when linking to
internal URLs. This will handle hosts, relative host names, changed
end points for you. It will also noticeably break so dead-links don't
linger in your code.
.. highlight:: jinja
Indentation within templates should be handled as such::
{% if indenting %}
<p>This is how it's done</p>
{% endif %}
.. index:: playdoh
Playdoh
~~~~~~~
New web-apps should be spawned from Playdoh_ and existing ones should
follow the spirit of Playdoh_. Playdoh_ collects lessons that several
Mozilla Django projects have learned and wraps them into a single
Django project template.
In the future, much of Playdoh_'s moving parts (Middleware, filters,
etc) will be moved into a separate library so these features won't be
lost.
See :ref:`packaging`.
.. _Playdoh: https://github.com/mozilla/playdoh
.. index:: code;javascript coding style
Javascript
----------
* Use JSHint_ — it's like JSLint_ but a bit more reasonable. JSHint
has options for assuming jQuery, node.js, and other options of use
to web developers writing JavaScript.
* Write QUnit tests when possible.
* Do not write JS in the HTML.
* Prefer single quotes over double.
.. _JSHint: http://www.jshint.com/
.. _JSLint: http://www.jslint.com/
.. index:: code;html5 coding style
HTML
----
* Use the HTML5
* Make sure your code validates
* No CSS or JS in the HTML
* Be semantic
* Use doublequotes for attributes::
<a href="#">Good</a>
<a href='#'>Less Good</a>
.. todo::
The previous list compiles to weird html where the list is a bunch
of separate lists.