Differences between revisions 25 and 44 (spanning 19 versions)
Revision 25 as of 2010-11-23 07:48:49
Size: 4421
Editor: mpm
Comment:
Revision 44 as of 2020-06-09 14:26:48
Size: 5003
Editor: AugieFackler
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
<<Include(A:dev)>>
Line 6: Line 8:

/!\ This page is intended for developers.
Line 15: Line 15:
== Some code doesn't agree with the coding style! ==

Yes, because some code predates the coding style and has not yet been rewritten to conform. Please follow the coding style for all new code.
Line 18: Line 22:
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. 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. Use a trailing underbar to avoid shadowing built-ins and imported modules.
Line 22: Line 26:
|| '''name''' || '''description''' ||
|| p1, p2 || first and second parents ||
|| f
ctx || a context.filectx instance ||
|| fn, fname || filename ||
|| fp || a python file(like) object ||
|| '''name''' || '''description'''                   ||
|| p1, p2 || first and second parents                   ||
||
ctx  || a context.changectx instance (or derivative) ||
|| fctx || a context.filectx instance
||
|| fn, fname || filename                   ||
|| fp || a python file(like) object                   ||
|| repo || a localrepo or review object ||
|| unfi || an unfiltered local repo instance ||
Line 30: Line 37:
We approximately follow [[http://www.python.org/dev/peps/pep-0008/|PEP 8]] guidelines for whitespace: We use [[https://black.readthedocs.io/en/stable/|black]] for most style formatting. Use it! An [[https://www.mercurial-scm.org/repo/hg/file/tip/contrib/examples/fix.hgrc|example configuration]] for the [[https://www.mercurial-scm.org/repo/hg/help/fix|fix extension]] which automates cleaning up style issues after commit.
Line 32: Line 39:
 * don't use tabs
 * use four spaces to indent
 * add a linebreak after a colon
 * use whitespace around most operators
 * don't use lines longer than 80 characters
 * don't leave trailing whitespace
Line 41: Line 42:
 * Mercurial is designed for Python 2.4 - 2.7 and onward so don't use features from 2.5 or later:
   * no conditional expressions
   * no unified try/except/finally
   * no Py3k-isms
 * Mercurial is designed for SupportedPythonVersions and onward so don't use new features:
Line 50: Line 48:
 * Think three times if you are a recovering Java programmer
 * Class names should still be lowercase
 * Class names should still be lowercase (but exception classes are `CamelCased`)
Line 53: Line 50:
 * Private methods and variables shoud be indicated with a leading underscore  * Private methods and variables should be indicated with a leading underscore
Line 90: Line 87:
== User options ==

 * Options are named `foo-bar` not `foobar` or `foo_bar`, also see [[UIGuideline|UI Guideline]] for more information.

Note:

This page is primarily intended for developers of Mercurial.

Coding Style

How to make your code pretty the Mercurial way.

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. Some code doesn't agree with the coding style!

Yes, because some code predates the coding style and has not yet been rewritten to conform. Please follow the coding style for all new code.

3. 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. Use a trailing underbar to avoid shadowing built-ins and imported modules.

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

name

description

p1, p2

first and second parents

ctx

a context.changectx instance (or derivative)

fctx

a context.filectx instance

fn, fname

filename

fp

a python file(like) object

repo

a localrepo or review object

unfi

an unfiltered local repo instance

4. Whitespace and syntax

We use black for most style formatting. Use it! An example configuration for the fix extension which automates cleaning up style issues after commit.

5. Language features and compatibility

  • Mercurial is designed for SupportedPythonVersions and onward so don't use new features:

  • Don't add default arguments to new functions unless you're going to use them

6. Classes

  • Think twice about using classes, functions are almost always smaller and simpler
  • Class names should still be lowercase (but exception classes are CamelCased)

  • Classes should derive from 'object'
  • Private methods and variables should be indicated with a leading underscore
  • Destructors in Python are not reliable and should be avoided

7. Unicode and character encoding

Character encoding is a complex topic (see Encoding Strategy for an overview) 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

8. Status and error messages

  • use _() to mark things for i18n

Short messages should look like this:

adding foo.txt

Note the following:

  • it starts with a lower-case word.

  • it has no trailing full-stop (.).

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:

  • The _ function is used to mark the string as translatable. Import it from the i18n module.

  • The string interpolation is done after the call to the _ function.

9. User options

  • Options are named foo-bar not foobar or foo_bar, also see UI Guideline for more information.

10. Miscellaneous

  • Don't put OS-specific hacks outside of util.py and friends
  • add docstrings
  • follow the HelpStyleGuide when adding help texts

11. 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/check-code.py --blame `hg manifest`
mercurial/i18n.py:42 (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.

12. See also


CategoryDeveloper

CodingStyle (last edited 2020-06-09 14:26:48 by AugieFackler)