File: style.rst

package info (click to toggle)
python-gsd 2.4.0-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye
  • size: 904 kB
  • sloc: python: 2,742; ansic: 1,881; makefile: 157; cpp: 109
file content (113 lines) | stat: -rw-r--r-- 3,493 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
.. Copyright (c) 2016-2020 The Regents of the University of Michigan
.. This file is part of the General Simulation Data (GSD) project, released
.. under the BSD 2-Clause License.

Code style
==========

All code in GSD must follow a consistent style to ensure readability.
We provide configuration files for linters (specified below) so that developers
can automatically validate and format files.

Python
------

Python code in GSD should follow `PEP8
<https://www.python.org/dev/peps/pep-0008>`_ with the formatting performed by
`yapf <https://github.com/google/yapf>`_ (configuration in ``setup.cfg``).
Code should pass all **flake8** tests and formatted by **yapf**.

Tools
^^^^^

* Linter: `flake8 <http://flake8.pycqa.org/en/latest/>`_

  * With these plugins:

    * `pep8-naming <https://github.com/PyCQA/pep8-naming>`_
    * `flake8-docstrings <https://gitlab.com/pycqa/flake8-docstrings>`_
    * `flake8-rst-docstrings <https://github.com/peterjc/flake8-rst-docstrings>`_

  * Run: ``flake8`` to see a list of linter violations.


* Autoformatter: `yapf <https://github.com/google/yapf>`_

  * Run: ``yapf -d -r .`` to see needed style changes.
  * Run: ``yapf -i file.py`` to apply style changes to a whole file, or use
    your IDE to apply **yapf** to a selection.

Documentation
^^^^^^^^^^^^^

Python code should be documented with docstrings and added to the Sphinx
documentation index in ``doc/``. Docstrings should follow `Google style
<https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html#example-google>`_
formatting for use in `Napoleon
<https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html>`_.

C
---

* Style is set by clang-format >= 10

  * Whitesmith's indentation style.
  * 100 character line width.
  * Indent only with spaces.
  * 4 spaces per indent level.
  * See :file:`.clang-format` for the full **clang-format** configuration.

* Naming conventions:

  * Functions: lowercase with words separated by underscores
    ``function_name``.
  * Structures: lowercase with words separated by underscores
    ``struct_name``.
  * Constants: all upper-case with words separated by underscores
    ``SOME_CONSTANT``.

Tools
^^^^^

* Autoformatter: `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`_.

  * Run: ``./run-clang-format.py -r .`` to see needed changes.
  * Run: ``clang-format -i file.c`` to apply the changes.

* Linter: `clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`_

  * Compile **GSD** with **CMake** to see **clang-tidy** output.

Documentation
^^^^^^^^^^^^^

Documentation comments should be in Javadoc format and precede the item they
document for compatibility with Doxygen and most source code editors. Multi-line
documentation comment blocks start with ``/**`` and single line ones start with
``///``.

See :file:`gsd.h` for an example.

Restructured Text/Markdown files
--------------------------------

* 80 character line width.
* Use spaces to indent.
* Indentation levels are set by the respective formats.

Other file types
----------------

Use your best judgment and follow existing patterns when styling CMake and other
files types. The following general guidelines apply:

* 100 character line width.
* 4 spaces per indent level.
* 4 space indent.

Editor configuration
--------------------

`Visual Studio Code <https://code.visualstudio.com/>`_ users: Open the provided
workspace file (``gsd.code-workspace``) which provides configuration settings
for these style guidelines.