Comments are attached directly to source code. They help the users, developers, and testers better understand the code. Static comments are markdown text and hash text. Dynamic comments are annotation that runs when the notebook is evaluated.
In production mode, only code cells should run. In annotation mode, code and annotation cells should run.
When a notebook is imported, the annotation cells should not run.
How are annotation cells done?
More details:
Here is a contrived use case:
(see miscjupy/Z.ipynb at main · Thomas-Walker-Lynch/miscjupy · GitHub)
The test0 annotation looks like it appears twice, but the first version is code that actually runs, and the second version is a screen shot left behind by the developer to show others what running it should look like. The second version is an image in a markdown cell. Annotation does not have to be of this form. It can be any sort of comment that benefits from introspection of the code.
When this is run standalone (__name__ == "__main__") the user can see a bit of what the expected output should look, and the intrepid sole who changes something can better know right away if something broke in a major way.
When the code is loaded using the Notebook loader found in the docs,
https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Importing%20Notebooks.html
the annotations also run. They are just dumped out after the import and have been disassociated from the source code, so they make no sense in the context of the importing notebook. It is no different than if when importing a notebook all the text comments were dumped into the importing notebook.
They are a disconnected mess.
The solution of wrapping annotations in if __name__ == "__main__" blocks does not work well for multicell annotations, as every single cell must be wrapped in an if block – and the result of the last line of this if block no longer echos to the output.
The solution of putting the annotations in a separate Notebook, and importing the Notebook to be tested causes such annotations to be disconnected from the source code. They are no longer annotations. (Imagine if the static comments had to be placed in a separate file!)
What is needed is a mode of execution or a kernel choice. In the ‘production’ mode only usual code cells run. In the ‘with annotations’ mode both code and annotation cells run.
Is there a means for doing annotations with Jupyter notebooks? If not directly, is there a person who is more familiar with the nuts and bolts of notebooks who can suggest a hack for getting this behavior?
… and if none of that … where may I propose adding this feature, as it really is very useful, and a natural fit to notebook style programming.
Thanks!