You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
1. We use [Poetry](https://python-poetry.org/docs/#installation) for managing virtual environments and dependencies.
4
-
Once Poetry is installed, run `poetry install` in this repo to get started.
5
-
2. For managing linters, static-analysis, and other tools, we use [pre-commit](https://pre-commit.com/#installation).
6
-
Once Pre-commit is installed, run `pre-commit install` in this repo to install the hooks.
7
-
Using pre-commit ensures PRs match the linting requirements of the codebase.
3
+
1. We use [Poetry](https://python-poetry.org/docs/#installation) for managing
4
+
virtual environments and dependencies. Once Poetry is installed, run
5
+
`poetry install` in this repo to get started.
6
+
2. For managing linters, static-analysis, and other tools, we use
7
+
[pre-commit](https://pre-commit.com/#installation). Once Pre-commit is
8
+
installed, run `pre-commit install` in this repo to install the hooks. Using
9
+
pre-commit ensures PRs match the linting requirements of the codebase.
8
10
9
11
## Documentation
10
-
Whenever possible, please add docstrings to your code!
11
-
We use [numpy-style napoleon docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/#google-vs-numpy).
12
-
To confirm docstrings are valid, build the docs by running `poetry run make html` in the `docs/` folder.
13
12
14
-
I typically write dosctrings first, it will act as a guide to limit scope and encourage unit-testable code.
15
-
Good docstrings include information like:
13
+
Whenever possible, please add docstrings to your code! We use
14
+
[numpy-style napoleon docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/#google-vs-numpy).
15
+
To confirm docstrings are valid, build the docs by running
16
+
`poetry run make html` in the `docs/` folder.
16
17
17
-
1. If not immediately obvious, what is the intended use-case? When should this function be used?
18
+
I typically write dosctrings first, it will act as a guide to limit scope and
19
+
encourage unit-testable code. Good docstrings include information like:
20
+
21
+
1. If not immediately obvious, what is the intended use-case? When should this
22
+
function be used?
18
23
2. What happens during errors/edge-cases.
19
24
3. When dealing with physical values, include units.
20
25
21
26
## Unit Tests
22
-
We use the [pytest](https://docs.pytest.org/) framework for unit testing. Ideally, all new code is partners with
23
-
new unit tests to exercise that code. If fixing a bug, consider writing the test first to confirm the existence of the
27
+
28
+
We use the [pytest](https://docs.pytest.org/) framework for unit testing.
29
+
Ideally, all new code is partners with new unit tests to exercise that code. If
30
+
fixing a bug, consider writing the test first to confirm the existence of the
24
31
bug, and to confirm that the new code fixes it.
25
32
26
-
Unit tests should only test a single concise body of code. If this is hard to do, there are two solutions that can help:
27
-
1. Restructure the code. Keep inputs/outputs to be simple variables. Avoid complicated interactions with state.
28
-
2. Use [pytest-mock](https://pytest-mock.readthedocs.io/en/latest/) to mock out external interactions.
33
+
Unit tests should only test a single concise body of code. If this is hard to
34
+
do, there are two solutions that can help:
35
+
36
+
1. Restructure the code. Keep inputs/outputs to be simple variables. Avoid
37
+
complicated interactions with state.
38
+
2. Use [pytest-mock](https://pytest-mock.readthedocs.io/en/latest/) to mock out
39
+
external interactions.
29
40
30
41
## Coding Style
31
-
In an attempt to keep consistency and maintainability in the code-base, here are some high-level guidelines for code that might not be enforced by linters.
32
-
33
-
* Use f-strings.
34
-
* Keep/cast path variables as `pathlib.Path` objects.
35
-
Do not use `os.path`.
36
-
For public-facing functions, cast path arguments immediately to `Path`.
37
-
* Use magic-methods when appropriate. It might be better to implement ``MyClass.__call__()`` instead of ``MyClass.run()``.
38
-
* Do not return sentinel values for error-states like `-1` or `None`. Instead, raise an exception.
39
-
* Avoid deeply nested code. Techniques like returning early and breaking up a complicated function into multiple functions results in easier to read and test code.
40
-
* Consider if you are double-name-spacing and how modules are meant to be imported.
41
-
E.g. it might be better to name a function `read` instead of `image_read` in the module `my_package/image.py`.
42
-
Consider the module name-space and whether or not it's flattened in `__init__.py`.
43
-
* Only use multiple-inheritance if using a mixin. Mixin classes should end in `"Mixin"`.
42
+
43
+
In an attempt to keep consistency and maintainability in the code-base, here are
44
+
some high-level guidelines for code that might not be enforced by linters.
45
+
46
+
- Use f-strings.
47
+
- Keep/cast path variables as `pathlib.Path` objects. Do not use `os.path`. For
48
+
public-facing functions, cast path arguments immediately to `Path`.
49
+
- Use magic-methods when appropriate. It might be better to implement
50
+
`MyClass.__call__()` instead of `MyClass.run()`.
51
+
- Do not return sentinel values for error-states like `-1` or `None`. Instead,
52
+
raise an exception.
53
+
- Avoid deeply nested code. Techniques like returning early and breaking up a
54
+
complicated function into multiple functions results in easier to read and
55
+
test code.
56
+
- Consider if you are double-name-spacing and how modules are meant to be
57
+
imported. E.g. it might be better to name a function `read` instead of
58
+
`image_read` in the module `my_package/image.py`. Consider the module
59
+
name-space and whether or not it's flattened in `__init__.py`.
60
+
- Only use multiple-inheritance if using a mixin. Mixin classes should end in
0 commit comments