Hacker News Reader

Comment by mFixman | Hacker News Reader

Jupyter is not great for collaboration with multiple people editing, but with a little bit of order it's perfect for in-person working and presenting that work.

Notebooks can be clean if you follow some rules:

1. Code flow always goes down: holding Option+Enter should execute all fields without any errors. Don't do `x += 1` if `x` is defined underneath.

2. All blocks are idempotent: running any block 5 times should produce the same result as running it 1 time. Don't do `x += 1` unless `x` is defined in that block.

3. Keep block-local variables short and block-global variables long. Don't do `x += 1` unless you are not using `x` anywhere else.

Also, the Table of Contents extension [1] is a life-saver for making long analyses workable.

[1] https://jupyter-contrib-nbextensions.readthedocs.io/en/lates...

View on HN

I have a rule that helps with hidden state and out-of-order execution. Once in a while I do a "restart kernel and run all cells." If doing that breaks anything, then I have to fix it. But it also ensures that a notebook is reproducible later on. Of course I don't have things that take hours to run.

It would be nice if there were something that would make out-of-order problems light up, the way that code editors can highlight errors while you're editing. A limitation of "browser as editor" is that it misses out on some of the powerful things that code editors do today.

Another thing is to put things in functions, so temporary variables are disposed of. That's a halfway step to putting things in .py files. A benefit if .py files is not always that jupyter is bad, but that variable scoping is good hygiene.

> It would be nice if there were something that would make out-of-order problems light up, the way that code editors can highlight errors while you're editing.

Check out https://github.com/nbsafety-project/nbsafety

Agreed on all points. Notebooks really aren't that hard to maintain. They just require some slightly different rules from standard scripts.

Personally, I like to label block-global variables in capital case (like PEP8 constants), so as to make them easy to spot. Being formatted like constants also causes me to think twice about altering it after instantiation.

I try to follow these ideas, and in many of my notebooks I frequently test them by occasionally running "restart kernel and run all cells" from the menu, which tends to point out anything I've accidentally moved or run out of order.

As a table of contents, I usually write some markdown up top with links to markdown HTML anchors elsewhere in the page, which themselves also have a link back to the TOC. Works pretty well. Will have to check out that extension.

Good rules. I will add some of mine:

4. Use a function in each block, that is defined and the called with appropriate arguments, and return the values of the block. This prevents proliferation of global state - and the functions are really easy to move out to .py modules when things have solidified a bit.

> with a little bit of order it's perfect for in-person working

It's not perfect for in-person working because a single person should always keep their work under version control, and they should be able to view meaningful diffs to understand the history.

It would be great to have tools available that force these rules on you.

Can we get these rules as flake8 rules? Would love to enforce this in projects.

Reply on news.ycombinator.com