Commenting & Discussion on Jupyter Notebook Cells

Collaboration is essential to our work in Jupyter notebooks and being able to comment on notebook cells is key to facilitating discussions with team members and other stakeholders.

During technical code reviews, for example, you might like your colleagues to comment on notebook cells to provide feedback, find bugs, and suggest improvements. Doing this kind of review on pull requests is ideal, as it’s easy to see what’s changed in notebook diffs.

But the review process doesn’t always call for you to create a pull request. Notebook diffs may not be valuable at every stage of the review process and not all stakeholders are proficient in Git or GitHub. Business and other stakeholders, for example, may prefer to share and review the final version of your notebook to ask questions and make decisions. When reviewing standalone notebook files, being able to comment on cells in the same way as we leave comments in Google Docs is more helpful.

ReviewNB is your solution for both types of commenting needs. For notebook code reviews, ReviewNB renders rich diffs of your GitHub commits and pull requests with the ability to comment on the cell or line level. For reviewing standalone notebook files, the ReviewNB JDoc feature enables a user to open any notebook in their GitHub repo and start commenting on any cell. It’s like Google Docs for Jupyter!

Let’s take a look at these two review workflows in ReviewNB.

Commenting on Jupyter Notebook pull requests

With ReviewNB, you can see rendered rich diffs of code changes on your pull requests and start discussions on your commits and PRs.

To comment on pull requests in ReviewNB, find the appropriate pull request on GitHub. Under the Conversation tab, find the ReviewNB bot’s message and click on the purple ReviewNB button.

You’ll see the rich diff view of the changes on the pull request. Click the + button at the single-line or cell level to start a discussion.

You can make comments on individual lines and cells, on the PR, or on the notebook. Segmenting your review in this way allows your team to focus on either cell-specific discussion or high-level PR concerns.

Commenting on notebooks without making a pull request

JDoc provides a simple and efficient way for teams to review Jupyter notebooks without having to create a pull request. This approach can be especially useful for:

• Ad-hoc analysis.
• A user that is not proficient with Git or GitHub.
• Reviewing newly added notebooks.
• Reviewing the final notebook version when incremental updates are not a concern.

To comment on your notebook using JDoc, open a repository in ReviewNB and navigate to the NOTEBOOKS tab.

Open the notebook you want to comment on and click the + button on either the single-line or cell level.

Once you’ve made a comment, any team member that is watching the repository or has participated in the conversation previously will get an email notifying them of the new comment. Users can unsubscribe from email notifications in the ReviewNB UI.

Users can reply, resolve, and start a new conversation or just skim through the comments.

Use the CHANGES tab to view the version history of this notebook.

JDoc tips:

• Make sure to either resolve or delete discussions that are no longer important to keep the notebook clear and relevant.

• Unlike discussions on pull requests, comments made on the notebook with JDoc will not reflect on GitHub. This is because GitHub does not support review outside of pull requests and commits

• Currently, if you change the name of a notebook, ReviewNB will treat it as a new notebook and previous JDoc discussions will no longer be visible. In future, we’ll provide a UI to specify renames and port over the comments.

Other methods for reviewing notebooks

Here are a couple of other options for leaving comments in notebooks.

• Google Colab allows you to comment on a cell-by-cell basis but it does not allow commenting on pull requests with rich diff. You can read more about the differences between ReviewNB and Google Colab on our blog.

• Deepnote provides a collaborative environment where you can work on Jupyter notebooks with others and leave comments for your collaborators. You can leave comments on individual cells or on the notebook as a whole. Deepnote integrates with GitHub to view notebooks in your repositories but it does not allow you to perform review on your commits and pull requests. Some other tools that have the same pros and cons are Hex and Databricks Notebooks.

• Curvenote provides commenting and versioning for Jupyter notebooks. Curvenote’s commenting system allows for threaded discussions on individual cells and users can reply to comments via email. Curvenote does not integrate directly with GitHub for version control, which means that you will need to use Curvenote’s version control system instead.

• A quick and easy way to give and receive feedback on notebooks is to share screenshots on Slack, but this is not an efficient way to manage the review as information can easily get lost or overlooked.

Conclusion

Performing reviews on Jupyter notebooks is an essential workflow for data science and ML teams. While pull request reviews offer valuable benefits like commenting with visual diffs, this workflow does not suit every circumstance.

Your best solution for leaving comments on notebooks is ReviewNB. With a simple GitHub integration, ReviewNB’s JDoc streamlines your review process and promotes effective communication by allowing users to comment on notebooks directly and have focused conversations.

Leverage the right tools for notebook reviews to help your team collaborate and deliver higher-quality outputs efficiently.