Function and Variable Naming
Conkeror variables and functions are named in all lower case with underscores separating words. If the identifier is part of a module, the name should begin with the name of the module. Abbreviate sparingly. Abbreviations in identifier names don't really make anyone's life easier. The Mozilla codebase uses the camelCase style for identifiers. This makes it easy to tell at a glance whether a given identifier is part of Conkeror, or part of the underlying Mozilla platform. We also find the underscore style easier to read. There are some exceptions to this guideline in the Conkeror source, but only for historical reasons. All new identifiers should follow this guideline for style.
New User Variables
If you use define_variable to add a new user variable to Conkeror, document it in UserVariables or in a page about the module the variable belongs to on this wiki.
Avoid pushing merge commits
The correct way to incorporate upstream changes with commits that exist only in your local repository is to git-rebase. Refer to GitHelp for more details.
Breaking Changes
If you make a change to Conkeror that is likely to break users' rc scripts, or a non-trivial change to the UI, announce it far and wide. Note it on BreakingChanges in this wiki, and announce it on irc and the mailing list. Update any documentation relevant to the change.
Long Strings
Break up long strings into several short strings, concatenated with the + operator.
Commit Messages
In order to play nice with GitWeb, it is best if commit messages are in the following form:
<blank line> 1 line briefly describing the change. try for less than 60 characters. <blank line> The change described in full detail. Wrap paragraphs to 60 or 70 characters.
Whitespace
- basic indent is 4 spaces.
- no tabs, not no way, no how.
- no extra end-of-line space.
- one blank line at the end of a file.
in function calls, no space between the function name and the following opening paren, e.g: foo().
in function definitions, one space between the name of the function and the following paren, e.g: function foo () {....
in inline functions, one space between the keyword function and the following opening paren.
one space between the name of any javascript statement keyword and the following opening paren, e.g: if (foo).
opening curly braces usually on the same line as the accompanying keyword: if (foo) { and function foo () {.
- the exception to that rule is that if the conditional form of an "if" spans multiple lines, the curly brace may need to go on the following line to provide visual separation between conditional and body.
- no parens around the "argument" to "typeof", because typeof is a keyword, not a function.
prefer not to perform an assignment inside of the conditional part of an if or a while, but if there is a good reason to, put an extra set of parens around it.
in javascript objects, no space between the key and the colon...e.g: { foo: "bar" }.
- generally follow the 80 column rule, but occasionally it's okay to make exceptions.
- and the one rule that might drive some people crazy, but works well in practice is that long strings like docstrings, or inline functions that get passed to define_* or interactive forms only get indented by 4 spaces, instead of lining up with the opening paren of the function. Conkeror makes extensive use of this style in order to have a lisp-like declarative API. Just pretend these forms are macros because indenting them this way keeps the source code from running ridiculously far to the right. Incidentally, the first argument to these forms should be on the same line as the function name because it makes grepping easier. Example:
interactive("paste-x-primary-selection", "Insert the contents of the X primary selection into the selected field or "+ "minibuffer. Deactivates the region if it is active, and leaves the point "+ "after the inserted text.", function (I) call_on_focused_field(I, paste_x_primary_selection));