Using Code Rocket's Flowchart and Pseudocode Tool Support

• Download CodeRocketSampleProject - 42.93 KB

Introduction

This article provides a walk through of a couple of iterations of designing and implementing a form of binary search algorithm using the Code Rocket plug-in for Visual Studio.

About Code Rocket   

Code Rocket is the newest kid on the block in terms of documentation tools. Like other tools it can pick up documentation from header comments above functions, but Code Rocket can also delve deeper into the actual internal workings of the function too, and allows you to visualize and document the function contents in both flowchart and pseudocode formats. See Figure 1 below for an example. It shows a sample C# function which has the Code Rocket visualization views docked beside it. Note: click on images to view larger sizes

 Figure 1. Code Rocket Sample Screenshot

Code Rocket comes as a plug-in for Eclipse (32 bit versions for Java development) and Visual Studio (2005, 2008, and 2010 for C# and C/C++ development). It won’t work in Express editions of Visual Studio because they don’t allow 3rd party plug-ins to be used.

Code Rocket also comes as a stand-alone designer which isn’t tied to any specific IDE. There’s more information about this on the Code Rocket blog.   

Purpose of Article

I wanted to provide a simple walkthrough of using Code Rocket during a typical development task to show you a bit of what it can do. I use it for C# development and I find that it provides some really valuable benefits such as:  

• Providing me with effective design and visualization support for algorithms and business processes that are being implemented; 
• Helping me to structure my code and to comment my code more effectively;
• Helping me to discuss and review my code with others at a higher level of abstraction, as well as visualizing test paths in complex methods; 
• Helping me to review and agree functionality with non-programmers, e.g. during requirements gathering with customers;   
• And of course it’s a documentation tool, so I can press a button and get the documentation I need.   

I’m going to use the Visual Studio version of Code Rocket with some C# code.

Installing and Activating Code Rocket  

Code Rocket isn't free but a 30 day trial can be downloaded here. You need to complete a simple registration to get a trial key (username and email address). Once installed, Code Rocket will have put the files in place necessary for Visual Studio to locate it as a plug-in to its IDE/environment.

When you launch Visual Studio you may see the “Code Rocket Trial” screen popping up. If you do, select the ‘Enter License’ option and then enter your email address and the trial license key that you will have been provided with to activate Code Rocket.

The first time you use Code Rocket inside Visual Studio you need to activate the Code Rocket tool windows. You will find these in the ‘View’ menu (Pseudocode Editor and Diagram View). See Figure 2 below. 

 

The Code Rocket components are just like any other tool window inside Visual Studio. They can be resized, positioned and docked into the IDE. Or, if you have your desktop spread across several monitors you could do what I do and have Visual Studio running in one monitor and have the Code Rocket components floating and displayed in a separate monitor.

Code Example  

I wanted to use a code example that may be fairly common from the world of data structures and algorithms – conducting a binary search. You may recall that a binary search allows you to traverse a list to locate an item of interest by attempting to halve the search space each time, therefore promoting efficiency in the search.

In this example, assume I have a sorted array of integers:

I want to utilize a binary search to locate the index position in this array of a specified integer value. For example, at what position is the number ‘42’? The answer is ‘9’.

In my code I have declared the prototype of a method which accepts the following parameters: a sorted array of integers to traverse; an integer value to locate within that array; and the start and end points within that array to seek for the value. Initially the start position will be 0 (the start index of the array) and the end position will be whatever the length of the array is. The method will return an integer representing the position within the array that the item being sought was located at, or -1 if no item was found.  The method will be called recursively, halving the search space each time until it finds the result or not. Here’s the method prototype: 

/// <summary>
/// Using a recursive binary search, locate the position within an array of a specified
/// integer value, and return that position.
/// </summary>
/// <param name="arrayToSearch">The array to seek for the item</param>
/// <param name="arrayValueToSeek">The value being sought within the array</param>
/// <param name="startPoint">The start position in the array to seek within</param>
/// <param name="endPoint">The end position in the array to seek within</param>
/// <returns>The position of the item found, or -1 if no such item</returns>
int GetPositionInArray(Array arrayToSearch, int arrayValueToSeek, int startPoint, int endPoint)
{
}

I will now implement the code for this function aided by Code Rocket. I’ll start off with a bit of design and then iterate that into code.  

NOTE: there are various ways of implementing a binary search (including the built in .NET framework classes) which could be the focus of an entire article in its own right. However this article is about Code Rocket and not binary searches per se. I will just work through one or two iterations of design and coding to demonstrate Code Rocket.

Design the algorithm using pseudocode and flowchart

Conducting the binary search requires traversing a list of items, attempting to halve the search space each time, usually by calculating the midpoint of the search space and deciding whether to look within the items prior to the midpoint or after the midpoint. It has been a wee while since I have used this algorithm therefore I want to have an opportunity to think it through prior to coding by laying out my thoughts in pseudocode. For this I can use Code Rocket’s Pseudocode Editor which is directly embedded inside Visual Studio. 

Here is my initial pseudocode design for the method: 

Code Rocket’s pseudocode editor helps with automatic indentation and coloring of keywords and can perform other typical editor tasks (copy, paste, etc.). First, I need to select the method in the code I want to view or edit the design of, and then type the pseudocode. See Figure 3 below.

 

When you enter pseudocode into Code Rocket it automatically creates a fully editable flowchart representation of the design too. I usually like to refer to the flowchart to get an alternative view of the design, to check for any obvious mistakes. You don't need to insert pseudocode to get the diagram, Code Rocket automatically creates the diagrams directly from your code too, i.e. the design views are fully synchronised with whatever is in the code. Figure 4 below shows what Code Rocket provided me with for the above pseudocode.
 

As mentioned the diagram is fully editable. You can drag and drop new items into the diagram or move items into new locations. Code Rocket provides ways of dealing with larger diagrams, e.g. pan, zoom, you can collapse and expand elements to see only the bits of the graph which are most relevant. You can select groups of elements which you want to group together into a single higher level element to reduce noise in the diagram for less interesting areas of code. There is also refactoring support, e.g. you can select a bunch of elements in the diagram (and any code attached to them) and refactor them into a new method. (Edit: this is currently only available in the stand-alone tool, not yet the plug-in). You can also print the diagram in various ways, e.g. print to fit a single page, print to spread over 2 pages wide by 3 pages height (or whatever combinations work best for the size of diagram and what you need to do with it).

One key benefit for me about the diagram is that you don't have to fiddle around with moving lines and boxes, you just drag and drop items where you want them and Code Rocket takes care of the layout for you.

Anyway, when I’m happy with the design I can click the ‘Commit’ button in the Pseudocode Editor or Diagram view and Code Rocket will inject a well commented, well formatted code skeleton for this design into the actual code for this method. Figure 5 below shows the resultant code skeleton.
 

/// <summary>
/// Using a recursive binary search, locate the position within an array of a specified
/// integer value, and return that position.
/// </summary>
/// <param name="arrayToSearch">The array to seek for the item</param>
/// <param name="arrayValueToSeek">The value being sought within the array</param>
/// <param name="startPoint">The start position in the array to seek within</param>
/// <param name="endPoint">The end position in the array to seek within</param>
/// <returns>The position of the item found, or -1 if no such item</returns>
public int GetPositionInArray(Array arrayToSearch, int arrayValueToSeek, int startPoint, int endPoint)
{
	// calculate the mid point of the search space (e.g. end position - start position / 2)

	// if mid point is valid (i.e. not less than zero)
	if ()
	{
		// if item at mid point is the item being sought
		if ()
		{
			// we have found the item

			// return the index pos of this item in the array (i.e. the value of midpoint)
		}
		// else if item being sought is less than the value of the item at the midpoint
		else if ()
		{
			// return result of calling GetPositionInArray recursively on lower half of array
		}
		// else
		else
		{
			// assume the item being sought is in the array contents somewhere after the mid-point

			// return result of calling GetPositionInArray recursively on  upper half of array
		}
	}
	// else
	else
	{
		// we have reached a point where we have exceeded the bounds of the search space

		// return invalid result
	}
}

I now need to go in and start filling in the actual code, but what I’ve gained here is design support and the ability to view the intent of my code at a higher level of abstraction. Note: the example presented here only shows a limited view of how Code Rocket handles comments in code. Multi-line comments are accommodated. You can have multiple lines of code underneath a single comment. If you don't have comments in the code Code Rocket will still provide you with pseudocode and diagram representations for it (and won't put comments in your code unless you specifically create or edit them through the design views). It also allows you to group things together at a higher level. You can enclose a whole group of code statements within Code Rocket comment tags so they only appear as a single larger element in the design views, rather than having a separate design element for each separate line of code. So there's quite a bit of flexibility here. I have added a brief example of this towards the end of the article.   

Anyway, continuing with our example Figure 6 below shows version 1 of my attempt to complete the code for the binary search method.
 

/// <summary>
/// Using a recursive binary search, locate the position within an array of a specified
/// integer value, and return that position.
/// </summary>
/// <param name="arrayToSearch">The array to seek for the item</param>
/// <param name="arrayValueToSeek">The value being sought within the array</param>
/// <param name="startPoint">The start position in the array to seek within</param>
/// <param name="endPoint">The end position in the array to seek within</param>
/// <returns>The position of the item found, or -1 if no such item</returns>
public int GetPositionInArray(Array arrayToSearch, int arrayValueToSeek, int startPoint, int endPoint)
{
	// calculate the mid point of the search space (e.g. end position – start position / 2)
	int midPoint = startPoint + (endPoint - startPoint) / 2;

	// if mid point is valid (i.e. not less than zero)
	if (IsInArrayBounds(arrayToSearch, midPoint))
	{				
		// if item at mid point is the item being sought
		if ((int)arrayToSearch.GetValue(midPoint) == arrayValueToSeek)
		{
			// we have found the item

			// return the index pos of this item in the array (i.e. the value of midpoint)
			return midPoint;
		}
		// else if item being sought is less than the value of the item at the midpoint
		else if (arrayValueToSeek < ((int)arrayToSearch.GetValue(midPoint)))
		{
			// return result of calling GetPositionInArray recursively on lower half of array
			return GetPositionInArray(arrayToSearch, arrayValueToSeek, startPoint, midPoint);
		}
		// else
		else
		{
			// assume the item being sought is in the array contents somewhere after the mid-point

			// return result of calling GetPositionInArray recursively on  upper half of array
			return GetPositionInArray(arrayToSearch, arrayValueToSeek, midPoint + 1, endPoint);
		}
				
	}
	// else
	else
	{
		// we have reached a point where we have exceeded the bounds of the search space

		// return invalid result
		return -1;
	}
}
 

After doing some testing, everything seems to be working reasonably well, but I have discovered a few issues with edge cases. One of these is that I need to check for the eventuality that both the start point and the end point to seek within have become zero. This could result in an infinite loop which will attempt to continually inspect the array item at index zero. Therefore I decide to add an extra check into the binary search algorithm to mitigate this case. NOTE: there is probably a more general issue here that it is not just when the start point and end point are both zero, but anytime the start and end points have the same value, this will signal the search has gone as far as it can without finding anything. However, I am just going to proceed with the ‘zero’ case for the time being.  

One way of adding the new check required would be to add it directly into Code Rocket’s design views, and then allow Code Rocket to merge the new logic into the existing code. Alternatively, I can just add the new logic directly into the code itself. One of the benefits of this is that Code Rocket will automatically detect the changes to the code and will automatically update its design components to reflect the latest state of the code – therefore making sure the design documentation is always up to date. See Figure 7 below.

 

I find this code synchronisation feature particularly useful. It means that I can write my code the way I want and Code Rocket will automatically pick up the information it needs to capture in its design views. I can then bring forward and consult the Code Rocket design views any time I want during coding, to visualize and explore the code in different ways.

Note: if you are wondering why some of the shapes in the diagram are colored green, this is Code Rocket’s way of indicating that there is actual code associated with these design elements, whereas the white shapes indicate things which are just comments in the code. The colors provide a simple overview of how much of the design has actually been coded up.

Anyway, I’m going to draw the article to a close at this point. Code Rocket can do lots of other things including standard documentation generation tasks, e.g. generate documentation for an entire project in HTML, PDF or Word formats. The generated documentation will include the pseudocode and flowchart visualizations but you can configure options to show or hide these and select different generation modes. I’ll try to post more articles for some of the other things that Code Rocket does in the future.

One final thing. I mentioned earlier that I would provide a brief example of some of the flexibility Code Rocket provides for grouping lines of code into elements within its design views. One of the options available are RQS region tags which allow you to group multiple lines of code into a single design element. Consider the imaginary code snippets below, not related to the binary search.

Let's say we have some steps in a web-based system for processing customer orders. Here is a code extract:

void SampleMethod()
{
	// get orders
	orders = GetOrders();

	// get estimated despatch date
	string despatchDate = GetDespatchDate();

	// while still orders to process
	foreach (Order o in orders)
	{
		// email customer despatch date
		o.Send();
	}


	// for each order
	foreach (Order o in orders)
	{
		// upload order to despatch system
		DespatchGateway.Upload(o);
	}

}

Standard Code Rocket processing would yield the following diagram in Figure 8  (given a bland name of 'SampleMethod') 

Figure 8. Diagram for Order Processing Code Extract

However, now consider the same code but into which we have added RQS region tags. Use "// RQS-" to start a region and to give the region a descriptive name. Use "// -RQS" to close the region. Any lines of code between the tags will be grouped together into this region. See below.

void SampleMethod()
{
	// get orders
	orders = GetOrders();

	// RQS- send despatch emails to customers

	// get estimated despatch date
	string despatchDate = GetDespatchDate();

	// while still orders to process
	foreach (Order o in orders)
	{
		// email customer despatch date
		o.Send();
	}
	// -RQS

	// RQS- upload orders to despatch system

	// for each order
	foreach (Order o in orders)
	{
		// upload order to despatch system
		DespatchGateway.Upload(o);
	}
	// -RQS
}

This will now yield the following diagram in Figure 9.

Figure 9. Effect of Code Rocket Region Tags on Design

As you can see all lines of code within the region tags have been grouped together into larger elements in the diagram, rendered as 3D boxes. This can be useful for methods which contain sections of small basic details that aren't necessarily relevant to see displayed explicitly in the abstract design views. Instead you may want the diagram to highlight some of the other more complex paths within the same method in greater detail. Code Rocket's diagram view will allow you to expand into these grouped elements should you wish to explore their contents more specifically. 

Summary   

In this article I have walked through a couple of iterations of designing and implementing a form of binary search algorithm using the Code Rocket plug-in for Visual Studio. I demonstrated the following: 

• Code Rocket’s support for up-front design using pseudocode and flowchart visualizations directly embedded inside the Visual Studio IDE;
• Code Rocket’s code generation capabilities for generating code from designs;
• Code Rocket’s ability to automatically synchronize the pseudocode and flowchart design views with respect to changes in code, so the designs don’t get out of date.  
• Some informaton about Code Rocket's code grouping options

Hope you like it! 

History

Version 1 Posted.

Version 1.1 - shortened article title and used text where possible to present code examples, instead of images/screenshots. 

Version 1.2 - fixed a few typos, provided additional details about Code Rocket's diagram editing capabilities and provided additional details about how Code Rocket works with comments, or not, in your code. 

Version 1.3 - made it clearer that Code Rocket is a commercial product. 

Version 1.4 - additional info about printing options and code synchronisation. 

Version 1.5 - added an example of Code Rocket's region tags 

Version 1.6 - fixed a couple of typos and grammatical issues introduced in Version 1.5

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)