Differences between revisions 1 and 26 (spanning 25 versions)
Revision 1 as of 2007-07-20 06:00:04
Size: 981
Editor: mpm
Comment:
Revision 26 as of 2011-03-16 12:16:37
Size: 4482
Editor: magenta
Comment: reference to unified try/except/finally
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
Don'ts: ## page was renamed from BasicCodingStyle
#pragma section-numbers 2
= Coding Style =

How to make your code pretty the Mercurial way.

/!\ This page is intended for developers.

<<TableOfContents>>

== Introduction ==

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

== 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:

|| '''name''' || '''description''' ||
|| p1, p2 || first and second parents ||
|| fctx || a context.filectx instance ||
|| fn, fname || filename ||
|| fp || a python file(like) object ||

== Whitespace and syntax ==

We approximately follow [[http://www.python.org/dev/peps/pep-0008/|PEP 8]] guidelines for whitespace:
Line 4: Line 33:
 * use four spaces to indent
 * add a linebreak after a colon
 * use whitespace around most operators
Line 6: Line 38:
 * don't name functions with CamelCase
 * don't name functions with lots_of_under_bars
 * don't make helper functions prefixed with do_
 * don't name your classes in Uppercase
 * in general, don't make ["mpm"] use his shift key any more than he has to
 * don't use default arguments without a good reason
 * don't use a class to encompass something that's not conceptually an object
 * don't use sorted(), rstrip(), or various other post-Py2.3 goodies
 * don't put OS-specific hacks outside of util.py and friends.
Line 16: Line 39:
Do: == Language features and compatibility ==
Line 18: Line 41:
 * use single quotes rather than double quotes
 * use a single underscore prefix for private methods and functions
 * use a single underscore prefix for a helper function
 * add a linebreak after a colon
 * 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 [[http://docs.python.org/release/2.5/whatsnew/pep-341.html|unified try/except/finally]]
   * no Py3k-isms
 * Don't add default arguments to new functions unless you're going to use them

== 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

== Unicode and character encoding ==

Character encoding is a complex topic (see [[EncodingStrategy|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

== 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.

== Miscellaneous ==

 * Don't put OS-specific hacks outside of util.py and friends
Line 23: Line 94:
 * use _() to mark things for i18n
 * add testcases to the test suite
 * run the test suite
 * follow the [[HelpStyleGuide||style guide]] when adding help texts
Line 27: Line 96:
-- ["mpm"] == 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.

== See also ==

 * [[ContributingChanges|Contributing changes]] - how to send us your changes
 * [[HelpStyleGuide|Help style guide]] - pointers on writing online help text
 * [[WritingTests|Writing tests]] - how to extend the test suite

----
CategoryDeveloper

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:

name

description

p1, p2

first and second parents

fctx

a context.filectx instance

fn, fname

filename

fp

a python file(like) object

3. Whitespace and syntax

We approximately follow PEP 8 guidelines for whitespace:

  • 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

4. Language features and compatibility

  • Mercurial is designed for Python 2.4 - 2.7 and onward so don't use features from 2.5 or later:
  • Don't add default arguments to new functions unless you're going to use them

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 (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

7. 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.

8. Miscellaneous

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

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/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.

10. See also


CategoryDeveloper

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