Roland Weigelt

YES! It’s official! I’ll be at the PDC in L.A., together with two other colleagues from the infonea product development team at Comma Soft AG. As flying from Germany to the West Coast of the USA is nothing I do on a weekly basis, I’ll take the opportunity to finally claim one of the prizes I won for GhostDoc in Roy Osherove’s add-in contest in August 2004 – a tour of MS offices in Redmond (which didn’t include transportation to Redmond ;-). I asked Josh Ledgard whether I could bring my colleagues, he replied “no problem”, so we’ll all take a little detour on our way to L.A. and visit the campus on Friday, 9th. before continuing our journey to L.A. on Saturday.

Sometimes it’s the simple things that can make you happy.

As I’ve already mentioned in my blog, I switched to a proportional font for editing source code long time ago, and I’m always looking how to improve my “source code viewing experience”. One thing I tried in Visual Studio .Net 2003 was bold text for keywords, but things were not working correctly. For example when typing “public”, you would see something like this:

• When you start typing, the keyword is not complete and thus the “publi” is rendered as normal text:
  
  
  
• After you type the “c”, Visual Studio detects the keyword “public” and renders it in bold text. Unfortunately, the cursor is not moved immediately…
  
  
  
• …but about 1 second later:
  
  

Well, maybe I could have lived with the delay, and the cursor position didn’t affect the typing of the next characters, but behind the bold keyword, the cursor display didn’t match the actual position. So I more or less forgot about it.

Now guess what I found out when I tried Visual Studio 2005: Not only that the bug regarding the cursor position is fixed, but “user types” (e.g. classes, interfaces) can now be styled individually, too. So now I’m able to have something like this:

Cool… The only problem is that I still have to use VS.Net 2003 for my daily work (man, I want that final out soooo bad!)

Remark: This is a spin-off of my work on GhostDoc. As the control I wrote for GhostDoc is highly specific to the actual problem I wanted to solve, I’ll only explain the basic idea and provide the source for the “LinkBox” control which I use as a base class. For some basic use cases this control may already be sufficient, for other use cases you’ll have to add some code.

Situation: I need something like this in one of my dialogs:

(Note this is a mockup inspired by an Outlook dialog,
not related to my work on GhostDoc)

Clicking a link raises an event, the event arguments provide information about which link was clicked.

If necessary, scrollbars appear:

Question: How do I implement this?

First thought: Web browser control. Why? Because of the links. Hmm… Do I need any other feature of HTML? No, just the links.

Second thought: In this case, a web browser control smells like overkill. So what else gives me multi-line text, links and scrolling? A RichTextBox control. While using a RichTextBox for text input (its main purpose) can be a bit frustrating, I’ve had good success in the past using it for output (see this and this post). And you can have links in rich text. By default, only http and mailto links are supported, but that’s a limitation that can be circumvented (see this CodeProject article by “mav.northwind”). Unfortunately, the RichTextBox control’s LinkClicked event only provides the text of the link — which can be a problem when trying to identify which link was clicked.

Third thought: If I’m able to crank out a user control for my specific needs with little effort, I’d definitely prefer that to using a web browser control. So what’s the simplest thing that would work for me? Do I need multiple links in one line? No. OK, so I can use a LinkLabel control for each individual line (which makes identifying which link was clicked pretty easy).

The solution: A user control completely filled with a panel (to get the sunken borders), link labels are added dynamically (with auto-sizing enabled) and are docked to the top, so I don’t have to take care of positioning. Scrolling is taken care of by the panel (AutoScroll), the AutoScrollMinSize is easy to determine as the labels are auto-sized (so width = largest width and height = y-coordinate of the last label’s bottom border).

The code can be downloaded here, complete with a demo project:

linkBox1.AddText("This is some fixed text");
linkBox1.AddLink("The quick brown {0}", "fox");
linkBox1.AddLink("jumps over the lazy {0}", "dog");
linkBox1.AddLink("This is a {0} with a tag object", "test", "Some tag object");

As already mentioned, the LinkBox control may be sufficient for simple use-cases. For more complicated use-cases (where you may need updating/refreshing), the control offers a SetText and an UpdateAutoScrollSize method (which in the GhostDoc source are called by a derived control). If you use LinkBox purely as a base class, you should think about making the methods protected — in a derived, application-specific control, you typically specify some sort of “data source” object and the control takes care of keeping the display up-to-date.

Implementation detail: This control uses docking for its layout, so the z-order of the LinkLabel controls is important. In general, when you add controls docked to the top in the forms designer and look at the resulting code, you’ll notice that the controls are added in reverse order. This reversed order is necessary because of the z-order that influences the docking. To achieve the correct z-order without the adding the controls in reversed order (which would make things a bit more complicated when adding controls programmatically like LinkBox does), you have to set the child index of the control:

thePanel.Controls.Add(theLinkLabel);
thePanel.Controls.SetChildIndex(theLinkLabel, 0);

In the case of the LinkBox control, this leads to the situation that thePanel.Controls[0] does not contain the LinkLabel control representing the first line. This is nothing you usually have to care about, I just mentioned it to avoid confusion in case you dig a little bit deeper in the debugger e.g. when running the demo.

Download the code

Excerpts from the “Visual Studio Hacks” book by James Avery have been published on the OnDotNet web site.

• Master the Command Window
• Create Comments Faster (this one is about GhostDoc and was written by me)
• Run Unit Tests Inside of Visual Studio
• Hack the Project and Solution Files
• Refactor Your Code

Unfortunately I didn’t have much time to read the book in the previous weeks. Yesterday was the first day of the year that the local “Freibad” (public outdoor swimming pool) was open, so I took it with me to read it while sunbathing. And I must say that “Visual Studio Hacks” passed my personal “Freibad test”, i.e. it was interesting enough to be read in a noisy environment, with interruptions (kids playing soccer in the sunbathing area), and without a computer nearby. Other books that passed this test in previous years are “C# Unleashed” by Joseph Mayo, “Code Complete 2” by Steve McConnell and the “Extreme Programming Pocket Guide” by chromatic.

Back to “Visual Studio Hacks”: I consider myself an advanced user of Visual Studio, so many of the hacks are not really new to me, but most of those hacks contained some bit of information I didn’t know yet or completely forgot about. What I really liked about the book is that it’s not a simple collection of tips that the author barely tried himself. You notice that in the little details like the solutions to problems you may not encounter immediately, but will run into sooner or later in your daily work (e.g. the infamous “Call rejected by callee” error). So far I’ve read the first half of the book and I couldn’t find anything that I would consider of little value – I wish could say that about many other computer books.

Development of GhostDoc is moving slowly, but steadily towards version 1.3.0, which will be the first release since October (wow, incredible how time flies by). So what has happened since the last GhostDoc News on this blog back in January? Looking from the outside, not much. If you remember the screenshot published back then, “all I did” was add the rule configuration tree to the configuration dialog and make all the buttons work:

Editing the settings of a rule looks something like this:

Behind the scenes, things have been far more complicated and time-consuming than expected. But the good news is that editing/exporting/importing the configuration (of rules and everything else) is pretty much finished.

So what’s the big deal about moving some configuration data around? I won’t go too much into detail, but simply imagine two computers A and B runnning GhostDoc (e.g. at home and at work) and you change some settings of a rule on A, change the priority of another (or maybe the same) rule on B. Then add some rules on A, remove some rules on B, and of course all these changes happened days after the last time you synced both computers. There are many opportunities to fry the user’s configuration data and while a fully automatic synchronization simply wasn’t possible, even just asking the user what to do (and then frying his/her data — nah, just kidding) already took a huge effort.

So what are the next steps? I’ll now write new text generation rules to solve some of the most often reported issues (e.g. “On…” methods) and the user defined rules mentioned in the January post. That will be pretty much the feature set for 1.3.0. Other ideas I have been playing around with will have to wait until 1.4.0 or later.

Visual Studio Beta 2

As people have been asking: Yes, I’ll look into releasing a version of 1.3.0 for Visual Studio 2005 Beta 2. There will not be a port of 1.2.1, though.

Other News

• I saw that GhostDoc is mentioned on the Microsoft Visual C# Developer Center — nice.
• There’s a new section on the GhostDoc home page, the “GhostDoc Hall of Shame” showing some of the more obscure results of the text generation. If you have weird/funny/sad/unexpected results, don’t hesitate to drop me a line.

I’ve received my free copy of Visual Studio Hacks by James Avery which I got for contributing hack #69 “Create comments faster” (page 280 – 285). These pages contain an introduction to – you may have guessed it – GhostDoc. After reading my part (of course ;-) I took a quick look at the rest of the book and I must say the first impression is really good. Obviously, after reading only a few pages, it’s too early for me to give a final verdict, so I’ll leave that for a later blog post.

A nice surprise for me is that my original text wasn’t edited that much (I wasn’t really sure what to expect, as English isn’t my primary language).

I’ve received a number of requests for a new GhostDoc feature for documenting a whole source file at once. This feature is filed as item #45 in my issue tracking system, and its status is “rejected”.

The texts generated by GhostDoc are suggestions generated by some stupid code that breaks identifiers into separate words and juggles them around. Each and every text generated by GhostDoc has to be checked by the developer, and should be revised by the developer if necessary. Depending on your coding style, the time required for checking and revising the generated text usually is less than writing everything from scratch, i.e. using GhostDoc saves you time.

So that’s the idea: GhostDoc guesses some documentation text, you check the results, and in the end you’ve saved some time.

I’m pretty sure that many of us know at least one “motivationally challenged” developer who is very likely to skip the part where you actually have to use your own brain. If such a person has to document a class member by member, there’s at least a little chance that he/she will notice texts that are just too stupid (e.g. such classics like “Toes the string.” and “Ons the click”). But can you imagine the same person given the feature of running GhostDoc on a whole source file at once? DailyWTF, anyone?

Alex writes about the impact of throwing an exception on performance and that it may not be as bad as one may assume. In the comments, people write that using exceptions for flow control is not the Right Thing to do.

Here’s my #1 reason why throwing an exception for flow control is definitely not a good idea: Debugging. When I’m debugging and I’ve set the debugger to “break on CLR exceptions” (and no, I don’t want to get more specific when I switch that option on and off dozens of times per day), I don’t want code execution to halt over and over again until I get to the actual problem.

It’s bad enough if some exceptions in non-exceptional situations cannot be avoided — I don’t need to introduce them in my own code.