Annotating source code

[To avoid confusion, annotations as I will be discussing them are not Java 5’s annotations (also known as metadata). I will be using the literal definition of annotation: a note added by way of comment or explanation.]

I have always been torn about the best way to conduct a code review. Sitting down with a developer in front of a screen and pointing out various elements (e.g. changes that can be made and identifying good approaches) is one approach. Unfortunately, this requires either party to write down proposed changes so that they may be followed up on. This leads directly to another approach: sitting down with a printout of the code so that annotations can be made directly on the printout. The problem in this case is that code does not usually want to be printed (even in landscape) and let’s not forget about the trees!

Ever since I used the “Reviewing” functionality in Microsoft Word a number of years ago I have wanted to apply the same principles to source code. For weekly code reviews, a developer and I would sit in front of a screen and walk through the code annotating the various issues. For daily code reviews I would be able to annotate the code and the next time the developer opened it, they would see the annotations.


Annotating Source Code

One of the primary stumbling blocks in implementing annotations in source code is storing the annotation data (e.g. the text, position, corresponding elements, and author). Given source code’s textual storage format, the annotations would need to be turned into language comments. If you’ve ever worked with an integrated UML tool or a visual UI builder then you know the hassle of having vendor specific elements nested in comments sprinkled throughout the code. It is easy to accidentially break the comment-based binding while performing normal edits to the code.

Ideally, source code (the stuff you see in your editor) would be independent from its storage format and the annotation data would be stored safely out of harms way.

This is the first of many entries that will be written around the notion of “software without text” or more succinctly: separating the view of programming language editing from its model or storage format. This is an idea that I have been enamored with for years. There are a number of “implementations” of the idea from Intentional Programming (IP) to a recent article by Sergey Dmitriev on his Meta Programming System. There are also entries on internationalizing, adding images and de-textifying source code as well as simplifying the understanding of code structure.



  1. Pingback: Simplifying code maintenance and understanding program flow « Rob's Random Ramblings

  2. Pingback: Internationalizing source code « Rob's Random Ramblings

  3. Pingback: Picture this « Rob's Random Ramblings

  4. Pingback: De-textifying programming languages « Rob's Random Ramblings

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s