|
|
|
# Coding Style
|
|
|
|
|
|
|
|
_This is a draft_
|
|
|
|
|
|
|
|
This document attempts to explain the basic styles and patterns that are used
|
|
|
|
in the MathJax codebase. New code should try to conform to these standards so
|
|
|
|
that it is as easy to maintain as existing code. Of course every rule has an
|
|
|
|
exception, but it's important to know the rules nonetheless!
|
|
|
|
|
|
|
|
This is particularly directed at people new to the MathJax codebase, who are in
|
|
|
|
the process of getting their code reviewed. Before getting a review, please
|
|
|
|
read over this document and make sure your code conforms to the recommendations
|
|
|
|
here.
|
|
|
|
|
|
|
|
# General practices
|
|
|
|
|
|
|
|
* Don't leave debug logging lying around.
|
|
|
|
* Use Unix-style carriage returns ("\n") rather than Windows/DOS ones ("\r\n").
|
|
|
|
You can convert patches with DOS newlines to Unix via the 'dos2unix' utility,
|
|
|
|
or your favorite text editor.
|
|
|
|
* Use two spaces for indentation.
|
|
|
|
* When fixing a problem, check to see if the problem occurs elsewhere in the
|
|
|
|
same file, and fix it everywhere if possible.
|
|
|
|
* End the file with a newline
|
|
|
|
* Declare local variables as near to their use as possible.
|
|
|
|
* For new files, be sure to use the right license boilerplate (TODO: add a link)
|
|
|
|
|
|
|
|
# Naming and formatting code
|
|
|
|
|
|
|
|
## Whitespace
|
|
|
|
|
|
|
|
No tabs. No whitespace at the end of a line.
|
|
|
|
|
|
|
|
## Line length
|
|
|
|
|
|
|
|
80 characters or less (for laptop side-by-side diffing and two-window tiling;
|
|
|
|
also for github and hardcopy printing).
|
|
|
|
|
|
|
|
## Indentation
|
|
|
|
|
|
|
|
Two spaces per logic level. No tabs. No whitespace at the end of a line.
|
|
|
|
|
|
|
|
## Mode line
|
|
|
|
|
|
|
|
Files should have Emacs and vim mode line comments as the first two lines of
|
|
|
|
the file, which should set indent-tabs-mode to nil. For new files, use this,
|
|
|
|
specifying two-space indentation:
|
|
|
|
|
|
|
|
/* -*- Mode: Javascript; indent-tabs-mode:nil; js-indent-level: 2 -*- */
|
|
|
|
/* vim: set ts=2 et sw=2 tw=80: */
|
|
|
|
|
|
|
|
## Control structures
|
|
|
|
|
|
|
|
Use K&R bracing style: left brace at end of first line, cuddle else on both
|
|
|
|
sides. Class and function definitions are not control structures; left brace
|
|
|
|
goes by itself on the second line and without extra indentation, in general.
|
|
|
|
|
|
|
|
## Names
|
|
|
|
|
|
|
|
* use interCaps for names: updateStatusBar.
|
|
|
|
* Properties of Jax object should be prefixed by the Jax name. For example
|
|
|
|
HTMLcreateSpan. |