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
Copy file name to clipboardexpand all lines: contributing.md
+6-8
Original file line number
Diff line number
Diff line change
@@ -52,7 +52,7 @@ The list of linting rules and exceptions are defined in the \`pyproject.toml\` f
52
52
53
53
## Git commit messages
54
54
55
-
While not strictly enforced, we suggest using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard for commit messages to aid in automatic changelog generation.
55
+
While not strictly enforced, we suggest using the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) standard for commit messages to aid in automatic changelog generation.
56
56
57
57
58
58
<aid="Documentation%20style%20guide"></a>
@@ -73,25 +73,23 @@ We use numpy documentation style (see [guide](https://numpydoc.readthedocs.io/en
73
73
74
74
## Code reviews
75
75
76
-
We follow multiple rules of the thumb on how to review code to maintain high quality for our libraries and the reproducibility of our results. Consider these points when reviewing others’ code or requesting one. The suggestions
77
-
78
-
Objects NOT to commit:
76
+
We follow multiple rules of the thumb on how to review code to maintain high quality for our libraries and the reproducibility of our results. Consider these points when reviewing others’ code or requesting one. You can read more on anti-patterns [here](https://github.com/quantifiedcode/python-anti-patterns/blob/master/docs/The-Little-Book-Of-Python-Anti-Patterns.pdf). Objects NOT to commit:
79
77
80
78
- Binaries: They cannot be version-controlled.
81
79
- Large files (>3MB): They slow down the repository.
82
80
- Do not push notebooks to the modules: They are hard to parse, obscure diffs and are much bigger than the equivalent script.
83
81
- Data: the only exception is tiny (<1MB) datasets for tests, but try to generate it as [pytest fixtures](https://docs.pytest.org/en/6.2.x/fixture.html) instead if possible.
84
82
85
-
Common anti-patterns to avoid:
83
+
Observed anti-patterns to avoid:
86
84
87
85
- One function can return types of output.
88
86
- Paths to local files: For full reproducibility we need to be able to access the data when it is publicly available. The exceptions for this are tutorial-like scripts and data that is not yet public. In the latter case use instead a folder present in the data location of the Imaging Platform (e.g., our server’s shared storage); add a comment to the url of the private repo pointing to the original files. This will simplify the refactoring when making the data public and ensure that the results are reproducible.
89
87
- Sample data contains unnecessary information: Everything not necessary to test the functionality of a component is noise, avoid commiting such type of data.
88
+
- Overusing Try-Except: This may make your code run but it may obscure edge-cases that bring bugs out to the open.
90
89
91
-
Highly-valued things:
90
+
Things that makes us happy:
92
91
93
92
- Lock your dependencies: Regardless of the library you use, please ensure you lock your libraries (e.g., poetry.lock) to ensure others can reproduce your environment.
94
93
- Document and specify the type all inputs and outputs: This makes code much easier to maintain over time.
95
-
- Avoid try-except systems unless you are using external libraries: These obscure actual failures
96
94
97
-
[WIP] We will enforce these rules using precommit files.
95
+
[WIP] We will enforce some of these items using precommit files.
0 commit comments