(2020-07-07) Code Comments As Live Wikis In IDEs

Andrei Chis: Code comments as live wikis in IDEs. In this article we explore how code comments can become a live wiki if we rely on interactive notebooks to document our systems directly inside the IDE.

Glamorous Toolkit is the moldable development environment made of multiple programmable and combinable components. One of the components is Documenter, the engine that makes creating and consuming code documentation and tutorials a beautiful experience directly in the IDE.

It enables:
documentation of existing code
tutorials
interactive data notebooks
This article explores the use of Documenter for documenting code

In spite of their wide usage, code comments can also be problematic.

In this article we explore how code comments, and the documentation about our software systems, can look like if we treat the IDE as a live wiki

A first class comment

This class models a face detected within a picture. We could comment this class as follows:

the comment talks about pictures and faces but only shows text; it has a code snippet but often the IDE offers no direct way to execute that code and explore the result; renames of classes and methods often do not take into account code snippets embedded into comments.

A different perspective

From snippets to executable examples

Example methods from a code comment can be directly executed when looking at the code comment

Embedding views

graphical representation of a face containing landmarks. One way would be to create an image with this information that we would then load, from disk or from an URL, and show in the comment.

A look under the hood

Enabling exploration

Diving into code

Diving into objects

Wrap-up

Writing code comments is a tedious activity. Alongside it we often do other activities like testing and building tools to explore and visualise our systems. These are often seen as activities independent of one another. However, that does not have to be the case.