Code Summarizer User Manual

Install Code Summarizer

Install Code Summarizer is very straight forward. Code Summarizer download is one single file:  CodeSumm_3.1.msi is a Windows Installer file, run this file to install Code Summarizer. Before starting install, please make sure: 1. Visual Studio 2005/2008 is installed on your computer; 2. All instances of Visual Studio are not currently running. In case you have Code Summarizer installed before, and installer complains install cannot continue before there is former version installed, you need to go to Control Panel -> Add/Remove program -> find Code Summarizer and remove it first.

Uninstall Code Summarizer

Uninstall Code Summarizer is as simple as uninstalling other program. Go to Control Panel -> Add/Remove programs -> Find Code Summarizer and remove it. When you start Visual Studio, you will see Code Summarizer is gone.

Change Font Setting

Before using Code Summarizer, it is strongly recommended to change screen font from Standard to ClearType. Right click on Desktop -> Properties -> Appearance tab -> Effects -> Check “use the following method to smooth edges of screen fonts”, select ClearType. Otherwise you may not get the same visual effect that this document describes.

Make Sure Code Summarizer Is Working

After install Code Summarizer, restart Visual Studio, it should be in place by side of solution explorer tool window. If it is not, do this in menu View -> Other windows -> Code Summarizer. Code Summarizer tool windows will appear as a tab by the Solution Explorer windows. If it is in floating mode or in a wrong position, drag the window and drop it to be docked as a tab beside Solution Explorer windows.

Activate Code Summarizer

Any downloaded Code Summarizer VS package is in trial state by default. You have the full functionality for 30 days. After that you need to go to www.seinative.com to purchase a product ID in order to continue to use this program. After acquiring product ID, right click on Code Summarizer map view area -> Activate Code Summarizer -> then input Name and Product ID to activate this package. Now Code Summarizer is in active state for ever until you download and install it another time.

What is Code Summarizer?

Code Summarizer is a code navigating/browsing tool for Visual Studio^® 2005 (referred as VS in this document). This software is designed as a VS package that is loaded by VS at the start up.  Code Summarizer resides in a tool window, which is normally located at the same position with the solution explorer and works as a side bar for the code windows that C++/C# programmers are working on. Code Summarizer works like an electronic map, with that user can zoom out/in. It allows users to view their code in very compact form without losing context. Just like a normal geographical map, when zoomed out, it still shows enough information for the user to locate where they are. Code Summarizer gives a bird’s view of the code the user is working on. This makes code navigation a lot easier. Fig. 1 shows the Code Summarizer (red line framed area) in a VS 2005 window with a sample project loaded.

Fig. 1 A Typical View of Code Summary Window in Visual Studio^® 2005

What Can Code Summarizer do?

As stated at the beginning, the main purpose of Code Summarizer is code navigation and code browsing. Code Summarizer gives user the flexibility of seeing big picture and the very code detail. The switch between the two is smooth and instant. Also, a code tip window allows user to browse code without zoom in.

Code Summarizer User Interfaces and Terminology

As shown in Fig. 1, Code Summarizer has three areas: on top is command buttons area (B), in the middle is search area (C), and at the bottom is the map area (E). Map area is divided into two parts: there are two sliders at the left and there is the map view at the right.

(In this document, file and document are used interchangeably and functions means functions or methods or properties. Also in this document, VS document, VS document window, VS code window refer to the same thing.)

B – Command buttons

Map Active Document – parse and display the current active document (there can be multiple documents open, only one is active) in map view.

Select an Open Document to Map – this command shows a list of all open text documents. User clicks on one of them to parse/display the selected document.

Refresh Current Map – reparse/show the document that the current map associated with. If there is no file ever mapped, then this command does nothing. Only reparse a file if the file has changed since last parse.

Refresh Current Selection – current selection means the current identifier (variable, function, class, macro definition …) under the input caret in VS code window at the time this document was mapped. Refresh Current Selection does not reparse a file, but redo the search of current selection. Current selection result is shown in search panel. That gives you a list of all appearances, and marks them in the map view.

Favorites – similar to Favorites in Internet Explorer, when you are in the function list window, or code markers windows or map view, you can add specific function, code marker line, or just a regular code line position to the Favorites list. This list is used for quick access to code positions.

Functions – a list of all functions/methods/properties (in C#).

CodeMarkers – a list of all line markers (breakpoints and bookmarkers).

Collection – a collection of functions/methods/properties from one or more files. This limits the code that the user has to deal with to a few points of interest.

C – Search Area

       In order to locate a code position of user’s interest, search is the most efficient way. The search function here is limited to the currently mapped file and does not have full featured search that Visual Studio provides. There are two different types of search.

 Fig. 2 Search Area and Search Results

      Current selection search – searches appearances of the current identifier (the one under input caret of the VS code window). This is done automatically when click Map Active Document, or select to open document to map. The result is shown under a yellow mark. Click the text brings up the list of all appearances. Result is also shown in map view.

     Text Search – this is just plain text search. Input text in the textbox, click Go button to do a search. You can also drag text from VS code window to the textbox. The result is shown under orange marker. Click text will bring up the whole list. Result is also shown in map view.

     Note: the search functionality can also be used as “goto line” function. Type a valid line number in the text box, press and hold CTRL key and click Go button, current line move to the line specified in map view.

E – Map Area

      D - Map Sliders

     There are two vertical sliders at the left side of map area. The bottom one changes code font size in map view. When slide up and down, it gives the effect of map zoom in/out. When zoom out to the bottom, it normally shows more than 300 lines of code in one window without scrolling. Of course the code lines are not recognizable, but this is not our concern, since we are not really interested in seeing the real code. We are interested in positions instead. See explanations later in map view. The top slider zoom code syntactically. It hides/shows code structures according its nesting level. The extreme zoom level shows only functions names. It is worth to mention that no matter how the code is zoomed, line markers, including search results can be overlapped, but never be hidden.

     You can also get the same effect using mouse wheel. Press/hold Ctrl key while rotating mouse wheel, you can achieve the result as the sliding the bottom slider. Use Alt key to get the effect of the top slider.

      A – Map View

Shown in Fig. 3, map view is where the parsed/mapped code shown. The left side of the window is margin area, where markers are displayed. On the right, code lines are shown in different size of font depending on the zoom level. The whole document is organized in code structures: name spaces, classes, structs, enums to functions, and code structures inside of functions.

 Fig. 3 Map View

Functions are framed and labelled drawn different colors to make them easy to recognize. Code structures inside of functions are the major focus. These code structures are:                         

• if blocks
• else blocks
• switch … case blocks
• try blocks
• catch blocks
• while blocks
• for blocks
• foreach blocks
• {} blocks

These structures can be nested with each other and makes up of the program logic. The fact that the code is mainly composed of these code blocks makes map view with unrecognizable font meaningful.

Code Summarizer does the following to make code easy to navigate and easy to browse:

• Highlight first line of the code blocks
• Draw lines at left of the code to mark the start point and end point of code blocks
• Code lines show patterns under small font
• Code line labels make code block more recognizable
• Instant code window

Code line labels are displayed on the right side of code line, which summarized the whole logic and program flow of the functions. User can toggle show/hide line labels by clicking on the function labels.

Instant code window is a large tip window popping up on the right side of the map view when you press CTRL or SHIFT key while moving cursor in map view. This window is large enough to hold 35 lines of code. When cursor moves, the code lines shown on the window changes accordingly. For browsing purpose, this window is very fast and the code line change is much smoother than scrolling in any regular document windows. This feature will be addressed later in this document.

Focal Point

Shown in Fig. 3, marked by a red circle, focal point is small blue circle that marks which line will stand still when zooming out/in. You can drag it up and down to the line you want to stay there still. Focal point changes when click one map view area.

Instant Code Window

Fig. 4 Instant Code Window

Press and hold SHIFT key while moving cursor on map view, a large tip window shows on the right side which displays code lines corresponding to where the cursor is on. Instant code window only goes away when you click on map view. This feature is mainly used for quickly browsing code to find out where you are, but use this window to carefully read code is useful too. The only limitation now is that the code is not syntax colored.

Other Interface Items

• When you right click on map view, there is a context menu, which allows to copy a single line, 5 lines, 10 lines, a function, and selection of code
• Show viewport/caret can move map scroll position to the current position in VS code window. A very useful feature, if you want sync the map view scroll position with VS document scroll position. That way where you are at in the map view while you are working on VS code window.
• Double click on the margin area of map view, current line moves to corresponding line in VS code window
• Press and hold ALT key and click on margin area to add/delete a bookmark to the line, a bookmark is added/deleted in VS code window as well
• If you add/delete a bookmark from VS code window, and this is the current file on the map view, the bookmark is synchronized on map view

What is the Advantage of Code Summarizer?

Code Summarizer belongs to Visual Studio productivity tools, specializing in code navigation/browsing. The idea of presenting code file in a map form is definitely unique in this category. It allows Visual Studio programmers to view their code in a different level, and move from one point to another without losing context. The map view is a new way to see your code. Also important is that when you see your code in this form time and time again, you know which code you are looking at without help from the instant code tip window. You are developing a visual form of the code functions in your mind.

Why is Code Summarizer Useful?

With MSDN and countless resources on the web, Visual Studio programmers usually don’t have much trouble to implement new functionality. New development is always easier to handle. Most of the time, programmers are dealing with projects that are big and are getting bigger. A code file of 5 -10 thousands of lines is not uncommon. And functions can grow to a thousand lines. Code blocks sometimes can be nested to a level of 10. In any of these cases, it is hard to identify where you are in the big picture, as you don’t have a big picture. Code Summarizer work especially well on large functions and deeply nested code. Regardless of the code size, with Code Summarizer at the left of your code window, it is like a road map to a forest. It is much easier to find or switch between code spots.

Limitations of Code Summarizer

Like other software, Code Summarizer makes tasks efficient by limiting problem domain. Currently Code Summarizer has the following limitations:

• Works with C/C++ and C# source code only, not Visual Basic at the moment
• Can map open documents only
• It takes a short while for you realize the true benefit it.

When/how Do I Use Code Summarizer?

Get your code mapped whenever you start reading, writing or debugging your code. Code Summarizer gives a clear idea where you are in your code. Keep the code points that you need to check on frequently in collection, then you don’t have to look around later on.

Code Summarizer is helpful in code navigation and browse in general, it is more so in the following situation:

• You are working on one part of the code, you need to switch to other parts of the program, same file or different files, and you want to come back very easily. You don’t want to losing context in this process.
• You are working on large functions, and you are lost in the code. You can not easily locate the start and end of the function, let alone specific position of the code.
• There is complicated logic in a function, with several nesting level of “ifs”, and you are lost.

In these situations, what you may want to do is map the files that are involved, find the functions by click Functions button. Right click on map view, on context menu, add this function to collection. Do this for all your points of interest. Click Collection button. You can add, delete and clear collection. This limits to just small portion of code to browse on. With the help of instant code window, you should have no problem to locate code lines and switch back and forth.