Advanced C/C++/C#
Code Visualization
for Visual Studio

Codekana 1.5 Documentation


1. General
2. Graphical Outlines and Syntax Highlighting
3. Search Results Highlighting
4. Definitions list Function
5. Miscellaneous Features
6. Codekana Settings Dialog
7. Troubleshooting, Tips and Other Notes
8. Support
9. Change Log

1. General

Codekana is a an add-in to Visual Studio which enables several advanced code visualization features for Visual Studio .NET 2002, Visual Studio .NET 2003, Visual Studio 2005 and Visual Studio 2008.

Codekana works with C, C++ and C# language source files, and it can be configured to work with other types of files by their extension. Its features are generally useful for all C-based syntax languages.

The general principle is that Codekana scans the source code while you edit it, and it uses the results of this analyisis to enhance the visualization provided by Visual Studio. All analysis is performed in a low-priority background thread, so that it won't interfere with normalCodekana operation. This means that enhanced visualization may take a short while to show up when you insert a large chunk of code, but it is generally instantaneous during normal editing.

The visualization enhancements in Codekana are designed to let you see the most salient features of the code at a glance. Colors are assigned according to control flow ('break' and 'continue' in loops are colored in the same color as loop keywords and delimiters), this way, you can see where there is a loop and whether there is any intermediate loop-exit or short-circuit point. 'return' is also highlighted separately, the same as 'if', 'else' and 'switch' blocks. Once you get accustomed to the coloring (and you can easily configure all colors to your hearts content), you will be able to grasp the control flow of a function without even having to read a single word.

Codekana provides the following visualization enhancements on top of Visual Studio's own syntax highlighting:

  • Keywords and delimiters (parentheses and braces) are colored according to the block's syntax function (red for loops, green for 'if' blocks, etc...
  • Parentheses are colored according to their function: one color for function calls and declarations, another color for expression grouping, and function-specific colors for if/loop/switch blocks.
  • Some specific keywords are colored according to their unique function: 'return', 'continue', 'case' and 'default' are colored according to their function, and 'break' is colored the same as loops or 'switch' blocks depending on the context.
  • The name of a function or class, or other defined symbol, are highlighted in the definition, so that it will stand out as a header from the code around them.
  • Unmatched delimiters (parentheses and braces) are specially highlighted in reverse colors, using the color of the type of block they are being used for, and in order to highlight the fact that they need to be closed. This allows correcting many simple typos before trying to compile the source code, and while you are editing it, thus resulting in a saving of time and frustration.

Apart from these main enhancements, Codekana brings in a few other features which can be of great help in your day-to-day coding experience:

  • When you perform a search using any of Visual Studio's mechanisms, Codekana kicks in and highlights all matches of the searched-for pattern, both in the current files and in any subsequent files you may visit. This allows you to find all matches at a glance
  • You can use Ctrl and the mouse wheel to zoom in and out by changing the font size quickly. Very nice to get an overview of a file, or to get a closer view of a function.
  • Codekana can highlight the current cursor line with a subtle, dotted border.
  • Codekana also can be configured to fix two "black spots" of Visual Studio language-sensitive auto-indenting: the indentation level of 'case' or 'default' labels in a switch statement, and the indentation level of 'public:'/'private:' labels in class definitions.
  • Finally, a new top-level "Codekana" menu is added with entries for the above functionality functionality, and a command called "Switch H/Cpp" which does exactly what you would expect: if you are in a C++ header or source file, it will switch to the other one (opening it if necessary).
  • Codekana Menu

I hope you will find Codekana a useful addition to your development arsenal!

2. Graphical Outlines and Syntax Highlighting

2.1. Goals

The goal of graphical outlines and enhanced syntax highlighting, as provided by Codekana, is not to get a more beautiful screen - the goal is to convey the maximum information in the least intrusive way, putting emphasis in the information that will benefit you most while coding. Here are the main points emphasized:

  • The code's structure should be apparent: outlines help give you a feel of the code's organization.
  • The code's control flow should be apparent: one- or two-way conditionals ('if' and 'if'/'else') are highlighted in consistent green and brown color), multy-way conditionals ('switch') is colored in blue, loops and loop control statements ('continue' and 'break') are colored in red, exception controlling code is colored in olive.
  • Unbalanced parentheses and braces should stand out from the code, so that you can fix them before trying to compile it and avoid the waste of time. Their color also conveys their function ('if' condition, function call, etc...)
  • When handling many nested blocks, you should be able to see exactly what each delimiter demarks. Control flow coloring allows to tell which delimiter ends a loop or closes a 'switch' block, and graphical outlines allow you to easily find the opening delimiter and preceding header from the closing one.
  • When reading the definition of a symbol (function, class, enum, or any of the other C/C++/C# basic constructs), it should be apparent what the symbol is. Especially given C-like language's declaration syntax, where the return type is given before the name of the function, this name is often difficult to locate visually. Codekana highlights it so that you can easily see which function you are in without having to read and decode the full header.

Colors and the intensity of the outlines are completely customizable using Codekana's settings dialog (located under the "Tools" menu), and you can turn each of them on or off according to your taste. It is recommended that you keep all of them on, though, as they all provide visual cues that, once accustomed, will allow you to understand code even before reading it.

2.2. Colored elements

For each block, these are the main elements colored:

  • The driving keyword ('if' for an 'if' block, 'while' for a loop, etc...)
  • The braces grouping the statements in the block.
  • For blocks with a control condition or structure ('if', 'switch', loops), Codekana colors the parentheses in the control condition for the block according to the function.

2.3. Main block types

Also, these are the main block types that Codekana understands and colors differently, with their default colors and the reasoning behind them:

  • 'if' blocks: colored in green, remembering a green traffic light.
  • 'else' blocks: colored in brown (dark red), remembering a red traffic light.
  • 'switch' blocks: colored in aquamarine (green-blue), as a distinct but calm color for these multi-way condition blocks.
  • loop blocks ('while', 'do', 'for'): colored in bright red. It's important to make these stand out, as loops is where control flow can spend a long time, and one should watch out for these 'hotspots'. Also, 'continue' and 'break' (when in a loop context) are colored red, so that you can see where the natural loop control flow is broken.
  • 'return' statements: this is colored in orange, less striking than loops' red, but you should see where the function can return.
  • exceptions blocks in olive: you can visually see where exception handling code is in a function in a simple way.

2.4. Additional block types

Apart from the coloring of these control-flow structures, which is the main part, data type declarators and other types of groups are also colored distinctly. Here is the list of the rest of colored blocks:

  • general, unspecific blocks: colored in dark purple by default, these are used for blocks you may add just to group statements or delimit the scope of your variables.
  • function body: dark blue by default, used for the body of function definitions.
  • class/struct/union definition: dark gree by default, used for the body of aggregate data types definitions.
  • enum/namespace: aquamarine (green-blue) by default.

2.5. Parentheses coloring

Apart from these brace-delimited blocks and their control structures, parentheses are also colored according to their function. This can help a lot when reading complex expressions. Here are the coloring groups distinguished by Codekana:

  • Function calls and function argument lists: colored in dark brown.
  • Expression grouping parentheses: colored in blue, without bold as the rest of the markers described above.

2.6. Defined Symbol highlighting (function/class name)

As another important element, Codekana highlights the class or function name in a class or function definition. This highlighting allows you to know where you are, especially when you have jumped to a certain point in the code by tracing with the debugger, or when double-clicking on a compilation error.

C-like languages' function declaration syntax is a case where the actual name of the function can get lost after a complex return type with multiple qualifiers and other types of modifiers such as 'template', etc... Codekana will highlight the symbol and that will let you know which function's body you are looking at with a simple superficial scan of the code.

2.7. Choice of default colors

The default colors in Codekana have been chosen to provide the highest amount of information with the least visual clutter. Also, since most programmers use either a white (or very light gray) or black (or very dark) background, Codekana will adapt the exact colors the first time it's run to your settings of choice.

If you don't like the colors, or some of them, you can change the configuration in Tools|Codekana Settings. You can also use the 'reset' button on this dialog to have Codekana recalculate the default colors with the current background (you then need to click 'Ok' or 'Apply' for these changes to take effect).

2.8. Outlining rules

Codekana will draw an outline for a braces or parentheses block if the following conditions are met:

  • The block's delimiters are properly matched, or have been so recently.
  • The block's delimiters are on different source lines.
  • Either both delimiters appear on the same column on the screen, or the first non-blank character in the line of the first delimiter is on the same column as the closing delimiter.

These rules allow Codekana to properly draw outlines for most One-True-Brace-Styles in common use.

3. Search Results Highlighting

When you are searching for the name of a variable or function, you are very rarely interested in just the first appearance of that name. Oftentimes, you'd like to visually see all matches, which will help in getting to the point where you are interested. The vim editor has had this feature for years, which is called 'hlsearch' (it stands for 'highlight search').

Codekana brings this feature to the Visual Studio editor. When you trigger a search in Visual Studio, using either of the various mechanisms available (the "Find" dialog box, the QuickFind combo-box, "Find in Files", the shortcut keys for "Find Next" or "Find Prev", etc...), Codekana will kick in and highlight all matches of the searched-for pattern. It will do so for the current file, but it will also keep highlighting them without getting in the way if you switch to a different source file.

After you have reached the position you were looking for, it's often the case that you are not interested in seeing these matches highlighted any more. Codekana provides a shortcut key which turns off the highlighting until the next search you perform, which is usually the best solution to benefit from the highlighting when searching and removing the clutter when not. By default, this is assigned to Alt-Minus, but you can change it in the standard Tools|Options|Environment|Keyboard options page (the command is called "Codekana.ClearCodekanaSearchHighlighting").

All VS search types are supported: literal strings, wildcards, and full regular expressions.

4. Definitions List Function

The Codekana Definitions List command allows the quickest navigation to any point in the current file. Press the default (Alt-Dot) to bring up a list of all definitions in the current module. While in this list, you can type partially the name of one of these functions (even different non-contiguous pieces, separated by spaces), and the list will be filtered. You can also use up/down to navigate the list. When you find the function you want to navigate to, press enter and you will be taken there:

Codekana GoTo-Function Dialog

5. Miscellaneous Features

Codekana provides several other features that enhance the Visual Studio development experience. Here are the details about these features:

5.1. Current line highlighting

Some people love it, some people hate it. As all other Codekana features, it's designed in order to improve your development productivity, but you can turn it on or off to suite your own taste. The advantages are that it allows you to locate where the cursor is quicker, and it will allow you to read tables more easily, but it is too distracting for some people.

It is implemented as a subtle dotted line the color of which you can configure. It is planned to provide the option of coloring the background in a future Codekana version, but some limitations in Visual Studio's coloring engine make it quite a feat to achieve without disrupting all the other coloring options of Codekana.

5.2. Zoom

Sometimes you need to see as much code as possible on the screen, to get an idea of the structure of the file you are seeing, or to fit a large function in a single screenful. Other times, you want a larger, more comfortable font size to work. Codekana provides an easy way to adjust that in a moment.

Following the convention of other programs, such as Microsoft Word, holding control pressed and moving the mouse wheel will zoom in and out the source code, actually by changing the "Font Size" setting. It also shows on the status bar the current point size configured for the font, so that you have a clear cue when you are adjusting the size.

You can also use the Codekana zoom command entries in the Codekana|Zoom menu to increase or decrease the zoom level. By default, Alt-Keypad-Plus and Alt-Keypad-Minus are assigned to zoom in and out, and Alt-Keypad-Times to restoring base zoom, but you can reconfigure to whatever you prefer in Tools|Options|Keyboard (type "Codekana.ZoomIn", "Codekana.ZoomOut" and "Codekana.DefaultZoom" to reach the commands).

5.3. Fixing autoindent options

It's great to have VS's syntax-aware automatic indentation. yet due to its non-configurable nature, if you don't agree what the "right" way to indent something is, there is no way to fix it. The most common offenders are the indentation level of 'case' and 'default' labels in switch blocks, and the 'public'/'private'/'protected' labels in class definitions.

Codekana provides the functionality to 'fix' these to the more common convention of indenting the labels one level from the containing braces. You can turn one or both on and off in the Codekana Settings dialog.

5.4. Switch h/cpp

One other missing feature in Visual Studio is the ability to switch quickly from the header to the source file of a class when developing in C++, which are usually kept in '.h' and '.cpp' files.

Codekana provides a new menu entry in the 'File' menu called "Switch h/cpp", which does exactly that. It is configured by default to use Alt-Comma as a shortcut, but you can configure that to your favorite key in Tools|Options|Environment|Keyboard (the command name is "Codekana.SwitchHCpp").

5.5. Extra file types

Codekana's parsing works fine both with C/C++ and C# files. It recognizes most structures in both languages, and applies all the highlighting described above. By default, it will only be active for files recognized as C/C++ or C# by Visual Studio.

But given the ubiquity of C-like languages, brace-block scripting languages, etc... it can also be useful in other language contexts. For this, Codekana can be configured to activate for other files by giving it a list of filename extensions to look for in the Codekana Settings dialog.

6. Codekana Settings Dialog

Here is a screenshot of the settings dialog, which can be reached from the "Codekana Settings" item at the bottom of the Visual Studio "Tools" menu:

Codekana Settings Dialog