TLDR:
Use Understand Annotations to review code with co-workers by annotating and sharing those annotations thru normal GIT operations without muddying up your source code or bogging down in weighty “review” processes. Slick!
Overview:
- Understand Annotations are notes that can contain text, links, #hashtags, and attached documents (files, images, PDFs, pictures of whiteboards, any file, any size).
- These Annotations (notes) are synchronized with any code entity – things like Files, Classes, Namespaces, Functions, even specific lines of code. But they aren’t stored in the source – they are linked via fancy parsing and stored in a GIT (or other method of sharing) and move around with normal checkin/checkout activities, but WITHOUT cluttering up your source files or directories.
- We will use Annotations and a simple #hashtag scheme to permit simple code review / cleanup in a lightweight, low bureaucracy, but high reward fashion. To leave a code review, we will Annotate and call it “#codecheck-ToDo” and when it is fixed we will change the hashtag to “#codecheck-Done”.
- This is a simple way to leave notes to yourself and to others, without a heavy process. It encourages review, even when a formal review hasn’t been started.
- With Understand Python API scripts you can send notifications that somebody left a message about code you are charged with maintaining.
The 2 Minute Tour of Annotations in Understand
You can leave an Annotation (note) about any entity or location in your code. They are stored in the Understand project and each user has their own file. These are integrated together by Understand to show a comprehensive view of all notes about the code.
Importantly, Annotations are not stored in the source – like comments, or even in the source directory. They are separate and are linked by our parsing technology in a way that survives over time and is easily shared via GIT or other file-sharing means.
To add an annotation, just Right Click on any entity in Understand:
Or in the editor you can Right Click on an entity, or hover over the right side of the editor:
If you click on the “…” it will load the Annotation Viewer. You can click on annotations to visit them, or click on … to see them.
Another way to see them is the Annotation Browser, available from Annotation->See all Annotations:
Useful Tip: Annotating entities, like functions, or classes, can help keep annotations synchronized accurately. In general, if the annotation is about a line – do it at the line, if it is about the entity annotate the entity.
Leaving Feedback/Reviews with Annotations and #hashtags
We will use three hashtags in our lightweight code review system:
#codecheck-ToDo – to leave an open review / suggestion / feedback
#codecheck-Done – to indicate that you accepted and remedied the feedback
#codecheck-Resolved – to indicate that the issue was resolved but not by a code change.
Examples:
Very simple! When you check in next, this will be updated and all will be well in the world.
Keeping Track of CodeChecks
As you browse files, Annotations are shown with …, or tracking as you scroll or click. The simplest way to see what is left to do, or what is done, or resolved, is to just do a filter on the #hashtag text you want to track:
Note also that the Annotation Viewer can be organized by who left the note, by where the notes are, or by the #hashtag.
The way to get a global view of where all #codecheck-ToDo can be found is to filter, and explore the Directory portion of the Annotation Viewer.
Where to Go From here:
If you place your Understand project in your Git (or shared location) then anybody checking out will see your comments or responses, as well as your fixes.
As they leave notes, you see them as well, with your filter.
It’s simple. Lightweight.
Use your imagination about what other things you could do with Annotations – learn about your code, and leave notes about what your learned, what you thought as you created or changed the code, or your plans for the future of it.
All without cluttering up your source code with tons of comments, or your source directories with lots of extra files.
Good luck – if you have questions, suggestions, or just need a bit of help contact us at support@scitools.com
