MoinMoin Coding Style

MoinMoin code has developed over the years (some parts more, some less) and got many contributions from many different people, so coding style in moin is not very homogeneous.

But the goal should be to improve it long-term - and for new code please follow the guidelines below so it doesn't induce boring cleanup work on others:

The long version

We mostly follow PEP 8 coding style (see also Python Idioms).

Especially:

• 4 blanks per indentation level. NEVER use TABS in *.py.

• New python files should be started by copying MoinMoin/_template.py
• Section "Whitespace in Expressions and Statements" should be strictly followed.
• Try to follow section "Naming conventions". We kill you if you use lots of single-letter names or stuff like "foo", "bar", "spam", "eggs" to obfuscate code. Even the usual "i" for a loop counter can often be named more meaningful. All core developers (and also all other python developers we know) also strongly dislike stuff like hungarian notation (str_name, itmrv_item etc.).
• For the docstrings, we use sphinx/rst.
• We use UNIX-style line endings ("\n" only, not "\r\n") for the source code files.

Except:

• We don't use <=79 characters line length. Even console windows can be made wider easily. So you do not need to break a 90 chars long line into 75 + 15 on the next line, that makes it just harder to read. Please do NOT mass-reformat old source code.

• We don't use Ctrl-L characters.
• We do multiple imports on one line (e.g. if they all come from stdlib and usually work).
• Section "Version Bookkeeping" does not apply as we don't use CVS-like mechanisms.

The short version

Write clean and readable code. If you don't need comments often because your code reads clear, that's great.

That does NOT mean that there should be no docstrings.

Vim Python PEP8 helper

If you are using Vim you can use python.vim - a really nice helper to write great looking code. Install it at ~/.vim/syntax/python.vim.

~/.vimrc

syntax on
set noai
set tabstop=4
set expandtab
set shiftwidth=4
filetype indent on

Automatic PEP8 checker

Since moin/1.7 branch we have an automatic PEP8 checker in MoinMoin/_tests/test_sourcecode.py. It contains a test generator that generates about 3600 tests (one test per file), so you get the checker's stdout per src file if the check for that file fails.

As of 2007-07-03, none of those tests fails. Please keep that state by running py.test before committing - and only commit if it has 0 failing tests.

MoinMoin Repository Commit Style

If you work on MoinMoin code and you would like your changesets to be acceptable for the main MoinMoin repositories, you should keep some stuff in mind:

Do commit often

Noone likes to dissect or review huge changesets.

If you work privately for some weeks or months on a new feature and your result is just one or a few changesets, that likely won't get accepted.

Do clean commits

Properties of clean commits are:

• they change one specific thing only (e.g. add one feature OR fix one bug OR fix typos/formatting)

  • you have to resist from fixing other stuff while you work on that one specific thing

  • you should keep notes about other stuff needing fixing, so you can do it after committing your clean changeset
• no unwanted changes, not even in whitespace (use hg diff often!)

• they should be complete (if you create new files, do not forget hg add. Use hg st and hg diff often.)

• they should not introduce unit test regressions

A good way to achieve this is to use hg diff and hg st very often, reading your changes again and again, line by line, word by word, thinking about your changes again and again - until you are completely happy with them. Then think about a good commit comment and commit.

Do good commit comments

Properties of good commit comments:

• they tell about what you changed in this changeset in a reasonably verbose way
  • what did you change?
  • where did you change?
  • why did you change?
  • how did you change?
• if you work in a separate repo that is for implementing feature X and that will get merged later into main repo, keep in mind that your comments need to be understandable in main repo context (== without context "feature X"), so you likely need to add this context to your comments, like "X: ...".

Reading hg diff and hg st output often helps in finding some reasonable commit comment.