Code comments as live wikis in IDEs

Utilizing interactive notebooks to document code through examples and custom views.

Andrei Chis
Mar 11, 2020 · 7 min read

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.


Code comments are pervasive in software development. They are used for many reasons, including, but not limited to, documenting design decisions, explaining what code does, clarifying implementation details, or showing how to use a piece of code.

In spite of their wide usage, code comments can also be problematic. Taking the time to refactor unclear code is sometimes better than explaining what that code does in a comment. Once written a comment needs to be kept up to date as the code changes, especially if documenting usage. Comments are more often than not only textual, limiting what the writer can embed.

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. As an example system we use a demo application that detects faces within pictures using the Azure Face API described in another article.

A first class comment

A class from our demo application is the class. This class models a face detected within a picture. We could comment this class as follows:

This is just one of many possible comments for this class. Still, it has characteristics often encountered in comments, like links to other code entities, and code snippets to show usage.

Nonetheless, 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.

This comment also aims to convey details about the structure and behaviour of a class. However, the tools that we use to view comments, more often than not assume that comments are pieces of static text meant only to be read.

A different perspective

Let us explore next a different way to consume this comment.

From snippets to executable examples

An important part of this particular comment is the code snippet. It shows how to create and initialise a object. Instead of having just a standalone code snippet embedded only in this comment, we transform the snippet into a standalone example method (a test method that returns an object), and embed in the comment a live editor for interacting with that example.

Code comments can embed code by taking it from example methods, instead of directly holding the code.

This makes it easier to maintain and test the snippet. It also makes it possible to execute it and inspect the returned object directly in the code comment. We do not need to copy-paste code, open another tool, or do any other kind of setup to run this code. Below we execute the example and explore the result.

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

The inspector in Glamorous Toolkit allows every object to have multiple custom views. Executing an example embeds in the editor an inspector on the resulting object. This enables us to use views as part of documentation.

For example, objects have a view showing how landmarks map onto the face that we can embed in the comment. Hence, our documentation does no longer have to consist only in static text or pictures. It can rely on live views created while a reader is interacting with the comment.

Examples also contain assertions. These are checked every time we run an example. Above we can see the green ‘Success’ label after the method name, indicating that all assertions passed. By running examples as part of our CI pipelines we can be a bit more confident that our documentation is up to date.

Embedding views

Often showing more graphical content in a code comment can be useful.

Let us consider that in our example comment we would find it useful to place, after the second paragraph, a 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.

Another alternative consists in expressing that graphical representation as a view of an object, writing an example method creating the necessary object, and embedding the resulting view in the comment.

Code comments can further embed live views for objects.

When executing an example we might not want to always show the entire inspector. Sometimes a single view is better. In our comment, the third paragraph talks about adding landmarks to faces that do not have a graphical representation. To show this we can write a dedicated example creating such a face object, and embed just the view showing landmarks.

The creator of a comment can decide to show a specific view when a reader executes an example method.

Now we have a story in our code comment. The initial view introduces a face with landmarks. Next we see the code to attach landmarks to a face, together with a view showing the positioning of those landmarks. At the end we get the complete code to create a face with landmarks and a graphical representation. We also get a full-fledged object inspector to further explore that object.

A look under the hood

Above we only see how the comment looks like, but not how the creator of the comment embeds views, or examples into the comment.

Documenter relies on a markup language (i.e., Pillar). Example methods and other artefacts are embedded through various annotations. For example the following annotation embeds the code of the example method .

We can see and edit these annotations directly in the comment by going with the cursor at the beginning of a line showing a view, editor or link. Below we see the annotation for embedding the view showing a face with landmarks.

Annotations are shown and can be changed when the cursor is placed near links, views or editors.

Hence, comments are still created and shared as text. However, they are no longer consumed as static text documents.

Enabling exploration

Understanding a software system is an activity that entails navigation through a web of interconnected code, run-time objects and data.

Diving into code

From a code comment a developer can navigate to any code entity referenced in that comment. All code entities referenced in a comment are by default buttons and open that entity in a new page to the right. For example, below, we start with the class and navigate to the class.

Navigating between code entities.

Explorations do not have to be limited to one single page. From the new page the developer can further continue the navigation. Below, the developer starts by looking at the class, dives into the class, continues by exploring face landmarks and finally face attributes.

We do not have to limit our navigation to a single code entity.

Diving into objects

Not only diving into code is needed. Sometimes, continuing the exploration by investigating an object can provide better insights. From a document, whenever an example is embedded in the document, the reader can continue the navigation by diving into that example.

Diving into an example object embedded in a code comment. Developers can further dive into the internals of that object.

As with code, explorations are not limited to a single page. The developer can continue for as long as needed. Explorations are also not limited to only code entities, or only objects. Both can be seamlessly intertwined.

A navigation session can intertwine objects and code entities.


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. The effort to write tests and build tools for our systems can be reused to improve the way we create documentation.

With Documenter if we structure our tests as examples we can directly embed them in our code comments and allow readers to interact with them. As examples return objects we can start from those objects, take inspector views that show them in interesting ways and embed them in comments. Each code comment becomes a live notebook.

Once we have a comment we can link it to other relevant code entities and objects, and enable readers to navigate through them. Comments become a live wiki where we can seamlessly navigate through code and objects.


feenk blog: Molding development to make your systems…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store