how could I miss this? Have been working with jupyterbook myself a lot lately (but for proprietary commercial work) and love it.
I am starting this issue for various (hopefully helpful and constructive) suggestions. I will add to this issue as I read through the various notebooks, so don't close.
In the chapter on programming style and magic numbers you give this example:
# enter the expected radius of nuclei here, in pixel units
approximate_nuclei_radius = 3
This would be a good place to mention that the convention for variables representing constant values in the code (Literals) in python
is to USE ALL CAPS.
Eg.
# enter the expected radius of nuclei here, in pixel units
APPROXIMATE_NUCEI_RADIUS = 3
If you assign to an ALL CAPS variable in your code, that should ring an alarm bell.
Also, while looking at this, it is a good suggestion to include units in variable names (if they are fixed and not configurable), e.g.
APPROXIMATE_NUCLEI_RADIUS_PX = 3
# vs
APPROXIMATE_NUCLEI_RADIUS_UM = 12
# vs
APPROXIMATE_NUCLEI_RADIUS_MM = 0.012
this of course is also useful for varibles that are not CONSTANT, such as
angle_rad, mass_kg, etc.
Jupytext
Maybe consider converting the source of this book to jupytext notebooks either with Myst-Markdown or py-percent. That way, it would be easier to actually submit PRs by just doing a few edits in the source with a text editor. It is not quite as trivial to edit the .ipynb as they also contain the cell outputs and potential collaborators may not have the same environment (lack of GPU) to regenerate the .ipynb with the output.
Hi @haesleinhuepf ,
how could I miss this? Have been working with jupyterbook myself a lot lately (but for proprietary commercial work) and love it.
I am starting this issue for various (hopefully helpful and constructive) suggestions. I will add to this issue as I read through the various notebooks, so don't close.
In the chapter on programming style and magic numbers you give this example:
This would be a good place to mention that the convention for variables representing constant values in the code (Literals) in python is to USE ALL CAPS. Eg.
If you assign to an ALL CAPS variable in your code, that should ring an alarm bell. Also, while looking at this, it is a good suggestion to include units in variable names (if they are fixed and not configurable), e.g.
this of course is also useful for varibles that are not CONSTANT, such as
angle_rad,mass_kg, etc.Jupytext
Maybe consider converting the source of this book to
jupytextnotebooks either withMyst-Markdownorpy-percent. That way, it would be easier to actually submit PRs by just doing a few edits in the source with a text editor. It is not quite as trivial to edit the.ipynbas they also contain the cell outputs and potential collaborators may not have the same environment (lack of GPU) to regenerate the.ipynbwith the output.