Development guidelines

If you want commit access, all we need is a SourceForge user ID.
Basically the only rules are:

1. Make sure your code actually compiles (to .pyc or .o) on a
   supported platform (e.g. a recent Mac) before checking in. (Sounds
   obvious, but people do forget sometimes.)

2. When changing existing functionality - even just bug fixes - always
   run the regression tests.

3. If you add functionality, also add a regression test if you don't
   want someone else to break it later.

4. Tread lightly when introducing third-party dependencies (we do this
   all the time, of course, but we try to do so in a way that avoids
   breaking the library for people who don't have the same dependency
   installed).

5. When in doubt, post your diffs to the cctbxbb for feedback.

6. Before committing code run libtbx.find_clutter and follow the output instructions for adjusting whitespaces and imports to cctbx standards.

[ Ignoring (1) or (2) can and will result in changes being reverted if]
we can't figure out how to fix it immediately.

Code Style Guide

In a nutshell

In general normal Python coding style guidelines apply. Additionally please be aware of this:

1. Be very conscious about avoiding redundancy in the source code
   (avoid cut-and-paste; if you copy more than one line it is
   probably too much).
2. no tabs, only use spaces for indentation and alignment
3. indent with 2 space characters per level
4. no trailing whitespace
5. wrap lines at 80 characters
6. only import functions you actually use
7. use only absolute and fine-grained Python imports

8. try to make the code self-documenting by using (long) meaningful
   names and by keeping functions small

9. Capitalization:

10. C++ (Boost conventions):
    • simple_identifiers_all_lower_case
    • TemplateParametersMixedCase
    • MACROS_ALL_UPPER_CASE
11. Python:
    • all_identifiers_all_lower_case
    • ExceptionsMixedCase

Please use libtbx.find_clutter to check your code before committing.

In length

Capitalization:

Strictly following the rules is more important in C++ than in Python
since C++ code is inherently more difficult to read.
Following the rules in Python helps when moving code from Python to C++.

• C++ (Boost conventions):
• simple_identifiers_all_lower_case
• TemplateParametersMixedCase
• MACROS_ALL_UPPER_CASE
• Python:
• all_identifiers_all_lower_case
• ExceptionsMixedCase

libtbx.find_clutter

To avoid problems with platform-specific end-of-line conventions
and stray whitespace characters such as tabs (see below) run the
command

$ libtbx.find_clutter

at the top level of each svn or cvs directory with changes to be
committed. The command will recursively traverse all subdirectories
and list the names of files that are not "clean." To minimize
the chance of accidents, libtbx.find_clutter does not modify
the files listed. A convenient option for cleaning up the problem
files is to use the libtbx.clean_clutter command, e.g.:

$ libtbx.clean_clutter path/to/file

One can also issue

$ libtbx.clean_clutter -c

which will recursively clean those files under the current directory which are modified or added, i.e. which would be committed.

To convert files with Windows or Macintosh end-of-line conventions
use the command:

$ libtbx.any2unix path/to/file

Why do we need libtbx.find_clutter?

We want to have an easy and reliable way to see who changed what exactly.

cctbx and phenix developers use many different editors. Some
remove trailing whitespace, some insert tabs, etc. Without
libtbx.clean_clutter we'd have a hard time seeing what was
actually changed since we'd have many spurious diffs in the
history.
(diff -b -w helps, but it hides indentation changes.)

Miscellaneous guidelines

Please use 2-space indentation throughout

It is extremely tedious to re-factor code written by authors
using inconsistent indentation.

Please break lines if they are longer than 80 characters

This will help make the sources more readable in various situations
(e.g. svn web view). Occasional longer lines are fine, e.g. for
certain assertions.
(Why 80 and not some other number? -- Obviously there has to be
some limit. 80 was chosen because it fits universally.)

Please use only absolute Python imports

Reasons:
- Scripts with relative imports cannot be moved to other locations.
- Python's relative import mechanism easily leads to confusion.

# Good example:
from iotbx import reflection_file_reader

# Bad example:
import reflection_file_reader

Please do not use import *

Reason:
- Reading code using import * is very difficult because
there is no easy way to tell where symbols come from.
- Name clashes may lead to subtle bugs.

# Good example:
from iotbx import mtz
mtz_object = mtz.object(file_name="any.mtz")

# bad example:
from iotbx.mtz import *
# name clash: built-in object, iotbz.mtz.object

Please use except KeyboardInterrupt in combination with bare excepts

Reason:
- A bare except will "swallow" keyboard interrupts (Ctrl-C),
forcing the user to hit Ctrl-C multiple times.

# Good example:
try:
  something()
except KeyboardInterrupt: raise
except:
  pass

# Bad example:
try:
  something()
except:
  pass