Please follow PEP8, the python style guide. There are a few static code checkers that can help you with PEP8 compliance including "flake8". PyCharm includes pep8 checks and can automatically fix pep8 problems.

When submitting a pull-request, don't reformat code unrelated to your work, even if the other code is not pep8 compliant. This clutters the "diff" and makes it difficult to review your changes.

Writing unit tests in a dynamic language like Python is very important. Writing tests is annoying, but it pays off big time. PyTest makes writing tests pretty easy, and MDTraj has some testing infrastructure to make it easier. We will probably refuse your pull-request if it doesn't include tests.

Tests should go in a file named test_modulename.py in mdtraj/tests/. Good tests each test a very specific piece of functionality. To test multiple functionalities, write more tests. Unlike normal programming, you can "copy-paste" code when writing tests.

Every function should have a docstring. This is critical. Most of the information in the documentation is pulled directly from the docstrings, which means that the docstrings are really important. For the same reason, it's really important that the formatting of docstrings is exactly correct. In order for them to be parsed, they need to be written in the numpydoc format. A detailed description of the numpy docstring format is available here.

in cython code, the function signature cannot be introspected directly, due to limitations of python. We get around that by writing the signature manually on the first line of the docstring. For instance, the docstring for XTCTrajectoryFormat.read() is below. Note that the signature comes before the 1 line summary.

"""read(n_frames=None, stride=1, atom_indices=None)

Read data from an XTC file

Parameters
----------
n_frames : int, None
    The number of frames you would like to read from the file.
    If None, all of the remaining frames will be loaded.
stride : int, optional
    Read only every stride-th frame.
atom_indices : array_like, optional
    If not none, then read only a subset of the atoms coordinates from the
    file. This may be slightly slower than the standard read because it required
    an extra copy, but will save memory.

Returns
-------
xyz : np.ndarray, shape=(n_frames, n_atoms, 3), dtype=np.float32
    The cartesian coordinates, in nanometers
time : np.ndarray, shape=(n_frames), dtype=np.float32
    The simulation time, in picoseconds, corresponding to each frame
step : np.ndarray, shape=(n_frames), dtype=np.int32
    The step in the simulation corresponding to each frame
box : np.ndarray, shape=(n_frames, 3, 3), dtype=np.float32
    The box vectors in each frame.
"""