Coding Style

How to make your code pretty the Mercurial way.

/!\ This page is intended for developers.

1. Introduction

This page is intended to save new developers a few round-trips when contributing changes. It doesn't cover everything, but it does cover some of the most common mistakes people make.

2. Naming conventions

For consistency and ease of reference, Mercurial uses a single style for all identifiers: all lowercase, with no underbars between words. This matches Python's core style (with the notable exception of has_key which is deprecated). For private methods and helper functions, the convention is to use a single leading underbar.

Throughout the code, the following variables usually refer to the same thing:



p1, p2

first and second parents


a context.filectx instance

fn, fname



a python file(like) object

3. Whitespace and syntax

We approximately follow PEP 8 guidelines for whitespace:

4. Language features and compatibility

5. Classes

* Think twice about using classes, functions are almost always smaller and simpler * Think three times if you are a recovering Java programmer * Class names should still be lowercase * Classes should derive from 'object' * Private methods and variables shoud be indicated with a leading underscore * Destructors in Python are not reliable and should be avoided

6. Unicode and character encoding

Character encoding is a complex topic, beyond the scope of this introduction, but Mercurial generally follows these rules:

* Almost all string data is manipulated either as plain byte strings in the local encoding or in no encoding * Mercurial-specific metadata like usernames is converted to UTF-8 byte strings in a restricted number of places using fromlocal/tolocal * Unicode objects are avoided wherever possible and no core APIs are designed to handle them

7. Status and error messages

Short messages should look like this:

adding foo.txt

Note the following:

Some existing strings don't follow this style and are kept like that for backwards compatibility reasons. But please write all new strings in this style.

The above message should look like this in your code:

ui.status(_('adding %s\n') % filename)

Please note:

8. Miscellaneous

9. Automated checking

A lot of the rules in this document and a bunch of others can be automatically checked with our 'check-code' script:

$ python contrib/ --blame `hg manifest`
mercurial/ (working directory):
 >     u = u'\n\n'.join([p and t.ugettext(unicode(p, 'ascii')) or '' for p in paragraphs])
 line too long

We recommend you run this script before every submission. In addition to catching style and portability issues in Python code, it will also inspect our C code and test suite.

10. See also