Annotating changes: a tool for helping with code reviews.

‘Review’ is a way of extending .NET Reflector so that you can not only browse the source code of NET assemblies, but can also comment on classes and methods, and use the tool as part of a Lightweight Code Review. Peli’s Review is a good example of a Reflector Add-in, which can be used in order to extend Reflector for specific purposes.

Why do you need a tool like this for code reviews?  You probably wouldn’t consider it for a formal code Review such as Fagan, but it is ideal for lightweight code Reviews. Where it comes into its own is where you are reviewing a module for which you do not have the source checked out. With Peli’s add-in, you can comment on compiled code in an assembly. With a large project involving several teams, this is a godsend, but it is handy for any project that is subject to rigorous source control. Your comments are stored separately, but can be consolidated with other review material. It is checked in and out separately from the code itself, and can be sent to the team responsible for the code.

The review Add-in is particularly useful if you have development teams across different locations. You can review a set of objects and associate your comments with a specific object. You can then email the xml file to your colleagues and they can load it up in .NET Reflector and the Review add-in: they will be able to match your comments with specific assemblies, classes and functions as well as specific code blocks.

Normally, you would be able to make comments as part of the source code, but if you were to be sent builds with no source code files, you wouldn’t be able to make comments in the source code itself. This is where this add-in can help.

Review is also useful if you want to:

• Annotate potential problems with the code (Coding Conventions, Error Handling, Resource Leaks, and Performance etc.)
• Make your own personal documentation as you learn more about the code and how it all links together

Review is for:

• Senior developers who need to review and understand the code of their team without necessarily having to check out the source
• Developers learning and understanding the APIs
• Testers learning what developers have implemented, and testers who are new on a project

Understanding an API

For many years, I have been using Reflector to help me discover how an API works.  In a similar fashion to performing a code review, learning an API is about studying the different sections, gaining knowledge and making comments in a centralised place.  Previously, notes about the API would have been lost in the sea of papers on my desktop, yet with Peli’s addin I can now have my notes and have them attached to the associated object.

In this example, I will be focus on an assembly shipped with ANTS Profiler 4 called RedGate.Profiler.UserEvents, which allows you to interact with the ANTS timeline.  If you haven’t done so, you can install Peli’s add-in using the following steps:

• Download the add-in from codeplex and extract from the zip file. Store your dll in the same folder as Reflector.exe file
• Open .NET Reflector and click on View > Add-Ins and click on Add. Browse to your Reflector.Review.dll and click Open and Close the Add-Ins window.
• To bring up the Review add-in, go to

Tools > Peli’s Review

This is how it looks like in .NET Reflector

The first stage of familiarising yourself with an API is to load the assembly, located, in our example, in the ANTS Profiler 4 installation directory into Reflector. At this point, with Peli’s Review Addin by our side we can start learning and making notes.

Disassembling the assembly displays the attributes which provide additional information about the object. Luckily, the assembly has a description, but I would like to define some more information.  By using the addin, we can add a new annotation by selecting Ctrl+W.  Any  annotation is associated to a code element (type, method, etc…) and contains a list of changes. A change is composed of a comment, a date, a user, a status and resolution.

Upon selecting Save, we are asked for the location where to save the file containing the annotations.  If you’re planning to share these annotations with the rest of the team, I recommend that you save the file with your source code and commit them into your source control repository. All data from an annotation is stored in an XML file. Multiple review files can be merged into one file. To avoid losing any information, changes are written to disk after each ‘commit’.

A review is stored in a file as XML. These files can be merged so that the annotations from the merged files appear in the current review.

Continuing on our investigation, we can dig deeper. The assembly contains two classes, after a quick investigation it becomes apparent that the Strings class doesn’t affect us.  It it would be nice to record this information for reference by another member of the team, or ourselves next time we look at the API.

The second class is called ProfilerEvent. The class has a series of overloads for a static methods called SignalEvent.  Based on my understanding of the assembly, this method should be called in order to raise the event for ANTS. We can add our new annotation with this information, along with any additional information you think would be useful – for example, a code sample of how to call the method.

At this point, we have an understanding of the assembly and we have made notes for future reference. The file is now ready to be shared with the team, allowing them to insert their own findings. For example, the next time we load reflector and the review file, we find A.Developer has added an additional comment relating to the ProfilerEvent class.

Going forward, when reviewing our own code, we can use the dropdown menus to indicate the status of the comments on the annotation itself.

Conclusion

Although Peli’s Code Review is conceptually simple, and designed for a fairly specific purpose, it is a remarkably useful tool in any circumstance where you need to document or take notes of any assembly.  Because the output is XML-based, it is easy to merge, or use to update the source documentation. I’ve shown an example where it can aid understanding of the way an API to a third-party assembly works, so a team can contribute and share their understanding. You’re sure to think of other uses once you start using it.