codestyle.rst

Code Style
==========


PEP 8 : the base Python style
-----------------------------
Python code should follow **PEP 8**

- https://peps.python.org/pep-0008/

Whereas C/C++ code should follow **PEP 7**

- https://peps.python.org/pep-0007/

We have a few requirements for our developers in addition to the original PEP8.
These are grabbed from the `Coding Guidelines for astropy-affiliated packages`_.

.. _Coding Guidelines for astropy-affiliated packages: https://docs.astropy.org/en/latest/development/codeguide.html#coding-style-conventions

- Only use 4-space indent
- ``import *`` is not allowed
- The use of automatic code formatters (e.g., Black) is strongly discouraged


Exceptions to PEP 8
-------------------

The following table summarizes all PEP 8 guidelines that are **not followed**
by the this Code Style Guide.

E501
   Allow lines to have > 80 characters, but <=120
E722
   Allow use of bare ``try ... except ...``
E121, E123, E126, E133, E226, E241, E242, E704, W503, W504 and W505
   They are ignored because they are not rules unanimously accepted,
   and PEP 8 does not enforce them.

.. tip::
    Click `here`_ for error code explanations and conventions

.. _here: https://pycodestyle.pycqa.org/en/latest/intro.html#error-codes


Naming conventions
------------------

All CSST Python source code is consistent with PEP 8 naming in the following ways:

- class names are ``CamelCase`` with leading uppercase
- function names should be ``lower_case_with_underscore``
- module variables used as module global constants are ``UPPERCASE_WITH_UNDERSCORES``


Code style check
----------------
Many tools can be used to check code style, such as

- PyLint: https://pylint.pycqa.org/en/latest/index.html
- Flake8: https://flake8.pycqa.org/en/latest/index.html
- pycodestyle: https://pycodestyle.pycqa.org/en/latest/index.html

All of them are from the PyCQA organization.
In our case, we recommend our developers to use the following command
(with pycodestyle) to check code style before committing code.

.. code-block:: bash

    pycodestyle ./**/*.py --ignore=E121,E123,E126,E226,E24,E704,W503,W504,E501,E722


Recommended IDEs
----------------
For writing Python packages, two powerful IDEs are worth to recommend:

- PyCharm: https://www.jetbrains.com/pycharm/
- VSCode: https://code.visualstudio.com/

Both of them have plugins or built-in tools to check code style.


Numpy-style docstring
---------------------
There are several popular docstring styles, namely Google, reStructuredText, and Numpy.
The CSST DAS adopts Numpydoc-style among the three.
We refer our developers to the Numpydoc official style guide for instructions on
how to write docstrings.

- https://numpydoc.readthedocs.io/en/latest/format.html

In particular, a complete example is available here.

- https://numpydoc.readthedocs.io/en/latest/example.html

In our case, we recommend the following method to check docstring

.. code-block:: bash

    python -m numpydoc --validate {YOUR_PACKAGE}.top_level_interface.{YOUR_FUNCTION/CLASS}

For example,

.. code-block:: bash

    python -m numpydoc --validate csst_proto.top_level_interface.flip_image

An example with typical Numpy-style docstring is shown below

.. literalinclude:: ../../csst_proto/demo.py
   :linenos:
   :language: python

.. note::
    Numpy-style docstring uses a two-section summary for functions / classes,
    including ``a short summary`` (usually a single line) right after the quote
    and a following detailed ``extended summary``.

.. note::
    The ``See Also`` section is not required for our development.

.. note::
    Presently, Numpy style docstring check is only performed on the functions / classes
    listed in the ``__all__`` variable in ``top_level_interface`` module.

Markup languages
----------------
Markdown and reStructrured Text are two of popular markup languages.
reStructrured Text is used in Numpydoc docstrings as well as sphinx-based documentation.
Markdown is much easier and usually used to write `README` for a package.

- Markdown
  - https://www.markdownguide.org/
- reStructured Text
  - https://www.writethedocs.org/guide/writing/reStructuredText/