Skip to content

Commit 1587414

Browse files
louieQlouieQ
committed
Update "Catalog of best practices" section in the README
1 parent f96f5d7 commit 1587414

File tree

1 file changed

+31
-27
lines changed

1 file changed

+31
-27
lines changed

‎README.md‎

Lines changed: 31 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -88,33 +88,37 @@ For further information on the available options, please refer to the project [d
8888

8989
## Catalog of best practices
9090

91-
In the following, we report the catalog of empirically-validated best practices on which Pynblint is based [\[1\]](#references).
92-
93-
For each guideline, we specify the current state of implementation within Pynblint:
94-
95-
- :white_check_mark: = "implemented"
96-
- :hourglass_flowing_sand: = "partially implemented / work in progress"
97-
- :x: = "not on our roadmap"
98-
99-
| State | Best Practice from [\[1\]](#references) |
100-
| ------------------------ | -------------------------------------------------------- |
101-
| :white_check_mark: | Use version control |
102-
| :white_check_mark: | Manage project dependencies |
103-
| :hourglass_flowing_sand: | Use self-contained environments |
104-
| :white_check_mark: | Put imports at the beginning |
105-
| :white_check_mark: | Ensure re-executability (re-run notebooks top to bottom) |
106-
| :hourglass_flowing_sand: | Modularize your code |
107-
| :hourglass_flowing_sand: | Test your code |
108-
| :white_check_mark: | Name your notebooks consistently |
109-
| :hourglass_flowing_sand: | Stick to coding standards |
110-
| :hourglass_flowing_sand: | Use relative paths |
111-
| :white_check_mark: | Document your analysis |
112-
| :white_check_mark: | Leverage Markdown headings to structure your notebook |
113-
| :white_check_mark: | Keep your notebook clean |
114-
| :white_check_mark: | Keep your notebook concise |
115-
| :x: | Distinguish production and development artifacts |
116-
| :hourglass_flowing_sand: | Make your notebooks available |
117-
| :white_check_mark: | Make your data available |
91+
Pynblint currently implements 22 linting rules based on empirically-validated best practices for collaborative Jupyter notebook usage:
92+
- 17 rules applicable to standalone notebooks
93+
- 5 rules applicable to entire data science repositories
94+
95+
These rules are derived from our comprehensive catalog of best practices collaborative notebook development [\[1\]](#references). Below is the current implementation state of linting rules associated with each best practice:
96+
97+
- :white_check_mark: Complete: Fully implemented
98+
- :puzzle_piece: Partial: Partially implemented with planned improvements
99+
- :hourglass_flowing_sand: In Progress: Implementation planned for future releases
100+
- :x: Not Planned: No implementation planned
101+
102+
| Best Practice from [\[1\]](#references) | **Status** | Details |
103+
| ------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
104+
| 1. *Use version control* | :white_check_mark: Complete | Fully implemented |
105+
| 2. *Manage project dependencies* | :white_check_mark: Complete | Fully implemented |
106+
| 3. *Use self-contained environments* | :hourglass_flowing_sand: In Progress: | *Planned*: detection of<br>- Python virtual environments (e.g., created with `venv`, `pyenv`, or `conda`)<br>- containerized environments (e.g., Docker). |
107+
| 4. *Put imports at the beginning* | :white_check_mark: Complete | Fully implemented |
108+
| 5. *Ensure re-executability (re-run notebooks top to bottom)* | :white_check_mark: Complete | Fully implemented |
109+
| 6. *Modularize your code* | :puzzle_piece: Partial | *Current*: detection of modularization constructs in notebooks.<br>*Planned*: modularization-focused refactoring recommendations based on detected patterns |
110+
| 7. *Test your code* | :puzzle_piece: Partial | *Current*: repository-level detection of coverage data.<br>*Planned*: detection of test modules/functions independent of coverage tools |
111+
| 8. *Name your notebooks consistently* | :white_check_mark: Complete | Fully implemented |
112+
| 9. *Stick to coding standards* | :puzzle_piece: Partial | *Current*: detection of cells with invalid Python syntax.<br>*Planned*: Integration of Python linters such as pylint, flake8, and ruff |
113+
| 10. *Use relative paths* | :hourglass_flowing_sand: In Progress: | *Planned*: identification of absolute paths instances in notebooks and recommendation of corresponding relative paths |
114+
| 11. *Document your analysis* | :white_check_mark: Complete | Fully implemented |
115+
| 12. *Leverage Markdown headings to structure your notebook* | :white_check_mark: Complete | Fully implemented |
116+
| 13. *Keep your notebook clean* | :white_check_mark: Complete | Fully implemented |
117+
| 14. *Keep your notebook concise* | :white_check_mark: Complete | Fully implemented |
118+
| 15. *Distinguish production and development artifacts* | :x: Not Planned | Implementation deemed infeasible (see the note below) |
119+
| 16. *Make your notebooks available* | :hourglass_flowing_sand: In Progress: | *Planned*: Pynblint will ensure that notebooks marked as published in its configuration are available online |
120+
| 17. *Make your data available* | :white_check_mark: Complete | Fully implemented |
121+
**Note**: Best practice #15 (Distinguishing Production/Development Artifacts) will not be implemented as there are no objective criteria for determining this distinction through static analysis of notebooks or repositories.
118122

119123
## License
120124

0 commit comments

Comments
 (0)