mirror of https://github.com/abinit/abipy.git
116 lines
3.7 KiB
ReStructuredText
116 lines
3.7 KiB
ReStructuredText
.. _coding-guide:
|
|
|
|
Coding guide
|
|
============
|
|
|
|
.. contents::
|
|
:backlinks: top
|
|
|
|
Committing changes
|
|
------------------
|
|
|
|
When committing changes to AbiPy, there are a few things to bear in mind.
|
|
|
|
* if your changes are non-trivial, please make an entry in the :file:`CHANGELOG.rst`
|
|
Note that the changelog is written following the format employed by the
|
|
`releases <https://github.com/bitprophet/releases>`_ Sphinx extension.
|
|
|
|
* if you change the API, please document the modifications in the docstring with the ``versionadded`` role::
|
|
|
|
.. versionadded:: 0.2
|
|
Add new argument ``foobar``
|
|
|
|
* Are your changes python2.7 compatible?
|
|
|
|
* Can you pass the automatic tests?
|
|
|
|
* Can you add a test to test your changes?
|
|
|
|
* If you have added new files or directories, or reorganized existing
|
|
ones, are the new files included in the match patterns in :file:`MANIFEST.in`.
|
|
This file determines what goes into the source distribution of the build.
|
|
|
|
Importing and name spaces
|
|
-------------------------
|
|
|
|
For numpy_, use::
|
|
|
|
import numpy as np
|
|
a = np.array([1,2,3])
|
|
|
|
For matplotlib_, **avoid** using the high-level interface such as in::
|
|
|
|
import matplotlib.pyplot as plt
|
|
plt.plot(x, y)
|
|
|
|
and use the object-oriented API provided by |matplotlib-Axes|::
|
|
|
|
from abipy.tools.plotting import get_ax_fig_plt
|
|
ax, fig, plt = get_ax_fig_plt(ax=None)
|
|
ax.plot(x, y)
|
|
|
|
It is recommended to pass the Axes ``ax`` to the plotting method and
|
|
use the decorator ``add_fig_kwargs``::
|
|
|
|
@add_fig_kwargs
|
|
def plot(self, ax=None, **kwargs):
|
|
"""
|
|
Plot the object ...
|
|
|
|
Args:
|
|
ax: |matplotlib-Axes| or None if a new figure should be created.
|
|
|
|
Returns: |matplotlib-Figure|
|
|
"""
|
|
ax, fig, plt = get_ax_fig_plt(ax=ax)
|
|
ax.plot(self.xvals, self.yvalsm, **kwargs)
|
|
return fig
|
|
|
|
Naming, spacing, and formatting conventions
|
|
-------------------------------------------
|
|
|
|
In general, we want to stay as closely as possible to the standard
|
|
coding guidelines for python written by Guido in `PEP0008 <http://www.python.org/dev/peps/pep-0008>`_.
|
|
|
|
* functions and class methods: ``lower`` or ``lower_underscore_separated``
|
|
* attributes and variables: ``lower``
|
|
* classes: ``Upper`` or ``MixedCase``
|
|
|
|
Prefer the shortest names that are still readable.
|
|
|
|
Configure your editor to use spaces, not hard tabs.
|
|
The standard indentation unit is always four spaces;
|
|
if there is a file with tabs or a different number of spaces it is a bug -- please fix it.
|
|
|
|
Keep docstrings uniformly indented as in the example below, with nothing to the left of the triple quotes.
|
|
|
|
Limit line length to (around) 90 characters.
|
|
If you wonder why we are violating pep8 that specifies a maximum line length of 79 characters,
|
|
check out this video by Raymond Hettinger:
|
|
|
|
.. youtube:: wf-BqAjZb8M
|
|
|
|
If a logical line needs to be longer, use parentheses to break it; do not use an escaped newline.
|
|
It may be preferable to use a temporary variable to replace a single
|
|
long line with two shorter and more readable lines.
|
|
|
|
Please do not commit lines with trailing white space, as it causes noise in diffs.
|
|
|
|
Writing examples
|
|
----------------
|
|
|
|
We have examples in subdirectories of :file:`abipy/examples`, and these are automatically
|
|
generated when the website is built to show up both in the :file:`examples`
|
|
and :file:`gallery` sections of the website.
|
|
Many people find these examples from the website, and do not have ready access to the
|
|
:file:`examples` directory in which they reside.
|
|
Thus any example data that is required for the example should be added to the :file:`abipy/data` directory
|
|
|
|
Testing
|
|
-------
|
|
|
|
Abipy has a testing infrastructure based on :mod:`unittest` and pytest_.
|
|
|
|
Common test support is provided by :mod:`abipy.core.testing`,
|
|
data files are storeed in :file:`abipy/tests/data`.
|