welcome: please sign in
location: DevelopmentGuidelines

Function and Variable Naming

Conkeror uses snake_case for variable and function names. That means they are lower case with words separated by underscores. By contrast, the Mozilla codebase uses camelCase style. This difference 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.

If the identifier is part of a module, it should begin with the name of the module. Abbreviate sparingly --- abbreviations in identifier names don't really make anyone's life easier.

Note that exceptions to this guideline can be found 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

We like to keep our commit history tidy. We also like it to be, whenever possible, a linear sequence of complete patches, each specific to one feature or fix, etc. Taking care up front to make good patches and keep the git history clean pays off later when we need to backtrack for whatever reason, like finding when a bug was introduced. Git provides all the tools to make this possible, from rebase to commit --amend to git-gui. Refer to GitHelp and other git documentation for more details.

Never rebase or otherwise edit the commit history of any branch on our official repository. (People depend on that one.) On your own clones, however, rebasing can be a nice way to keep your patches tidy for other developers and users. We won't mind.

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 & Style

conkeror-minor-mode

If you're an emacs user, there's an emacs minor mode designed to help you follow these guidelines. It's called conkeror-minor-mode and:

  1. It automatically follows this indentation style for "macro"-like functions.
  2. It warns you if you break any of the other whitespace guidelines.
  3. It provides syntax coloring of functions and variables.

Conkeror.org: DevelopmentGuidelines (last edited 2013-10-31 22:29:14 by BruceConnor)