Conventions

Python code

pep8 covers Python code conventions.

pep257 covers Python docstring conventions.

Minor caveats:

HTML/Django templates

http://mozweb.readthedocs.org/en/latest/coding.html#html

We use the same HTML style conventions that Mozilla webdev does.

CSS

Todo

css conventions

JavaScript

http://mozweb.readthedocs.org/en/latest/js-style.html

We use the same JavaScript style conventions that Mozilla webdev does.

Git

I encourage good commit messages in a form that works well with git’s various commands. Something like http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html. except that I don’t care about verb tense or capitalization and if the commit message is tied to a bug report, the bug report number should be the first thing in the first line. Here’s the tbaggery example with some adjustments:

475. short summary (50 chars or less)

More detailed explanatory text, if necessary.  Wrap it to about
72 characters or so.  In some contexts, the first line is
treated as the subject of an email and the rest of the text as
the body.  The blank line separating the summary from the body
is critical (unless you omit the body entirely); tools like
rebase can get confused if you run the two together.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet,
  preceded by a single space, with blank lines in between, but
  conventions vary here

- Use a hanging indent

Why? Here’s the reasons:

  • 50 characters or less works well with the various git commands that show only the summary line and also on github.
  • Having the bug number as the first thing makes it easy to see which commits covered which bugs without parsing the commit message. We do that a lot (“When did the fix for bug xyz land?”).
  • Wrapping the subsequent paragraphs allows them to show up nicely in git output as well as on github.

Why not the other things? Here’s the reasons:

  • Capitalization or non-capitalization for a phrase doesn’t affect the output of git commands or my ability to quickly parse a summary.
  • Ditto for verb tense.
  • I’m all for ditching convention baggage for things that don’t matter.