Archives
-
Looking back, looking forward...
2005 was an amazing year…
- GhostDoc became really popular (the VS2005 version alone had over 6000 downloads since the release in early November).
- The PDC was a great experience, and visiting Microsoft before that was a lot of fun.
- Being part of the “Show Off” session was nice; unfortunately it was pretty late, so people started leaving the movie theater before my video was even shown.
My plans for 2006 (to be more exact, those related to .NET)
- GhostDoc: After doing a bit of work after Christmas, it became clear that GhostDoc 2.0 will be a “large” release. Internally I’ll do some heavy refactoring on certain, isolated parts, throwing out some historical junk and moving to “C# 2.0 style” code.
- Things I want to learn: From my current point of view, WPF is the thing I want to dive into.
- Things I want to do: I’m in the process of founding a local .NET user group for the Bonn area, called “Bonn to Code” (yup, pun intended – all credit for that name goes to my colleague Jens Schaller).
-
GhostDoc 1.9.2 (for Visual Studio 2005) Released
Version 1.9.2 is a bugfix release of GhostDoc for Visual Studio 2005 (download on the GhostDoc homepage).
VB.Net support will still remain experimental in this release, so it is turned off by default and you have to turn it on in the configuration dialog. It will become official in the next feature release, which I’ll be working on over the Christmas holidays.
Important: When updating from 1.9.0 please follow the instructions in the ReadMe.htm file in the ZIP archive. Users of 1.9.1 please uninstall before installing – an upgrade installation will not work correctly*.
ChangeLog:
- Fixed: Installation issues with the US version of Visual Studio 2005 running on a non-US operating system version (e.g. German WinXP).
- Fixed: "Custom text" feature (see "Options" tab on the configuration dialog) was broken since 1.9.0.
- Fixed: The rule for event-related "On..." methods generated text with the name of the event splitted into individual words. Now the original name of the event is preserved; in order to achieve that, new macros have been added (see below).
- Added: New "Verbatim" property of the "Words" macro. Example: for the method name "SayHelloWorld"
$(MethodName.Words.ExceptFirst)returns "hello world"$(MethodName.Words.Verbatim.ExceptFirst)returns "HelloWorld".
________________________
*) I’m using an installer class during setup, which in an upgrade installation is affected by a bug in MSI (known since 2002, btw). An upgrade installation is only possible without problems if the code of the installer class does not change – I hope that the changes in 1.9.2 to the installation are good enough for a couple of versions ;-) -
Code Snippet for Test Method
Name: Test Description: Test method for NUnit Shortcut: test Result: [Test]
public void TestName()
{
}Download: Test.snippet -
GhostDoc 1.9.1 (for Visual Studio 2005) Released
Version 1.9.1 is a bugfix release of GhostDoc for Visual Studio 2005 (download on the GhostDoc homepage).
The VB.Net support will remain experimental in this release, so it is turned off by default and you have to turn it on in the configuration dialog. A couple of issues (caused by small differences between the C# and the VB.Net CodeDOM) have been fixed, and things are looking good in general so I’m confident I can drop the experimental status pretty soon.
Important: When updating from 1.9.0, please uninstall 1.9.0, start Visual Studio once, exit and then install 1.9.1. If you have customized your configuration, please export it before uninstalling 1.9.0, then import it after installation of 1.9.1. All steps are explained in detail in the ReadMe.txt file in the ZIP archive.
ChangeLog:
- Fixed: Use of generics causing documentation not being generated.
- Fixed: Installation not possible if "My Documents" folder is on network drive/share.
- Fixed: VB.Net support: Inherited documentation causing either error messages or mixed up comments.
- Fixed: VB.Net support: Property accessors being treated as methods.
- Fixed: VB.Net support: Minor differences between C# and VB.Net CodeDOM causing trouble.
- Fixed: Some add-in issues (uninstallation, add-in manager)
- Changed: The add-in is no longer installed to a sub-folder of the AddIns directory. Instead, any location can be chosen now on the harddrive.
- Changed: In the generated comments, references to types ("<see cref="..." />) are now using the "T:" prefix that you may know from the inherited comments. This is to avoid the (new) warnings that Visual Studio 2005 is generating.
Thanks to Markus Hogsved for his detailed feedback on VB.Net support.
-
Code Snippet for Events
Name: Event Description: Code snippet for an event and the corresponding On... method Shortcut: event Result: public event EventHandler<EventArgs> EventRaised;protected virtual void OnEventRaised( EventArgs e )
{
EventHandler<EventArgs> handler = this.EventRaised;
if (handler!= null) handler( this, e );
}Download: Event.snippet (Update 2005–11–23: Changed to make the “On...” method thread safe. Thanks Eric!
D’oh… I even wrote about this in January, but as thread safety wasn’t an issue in any of my code, I went back to the “old pattern” at some point, as it meant less typing. But a code snippet should of course use the correct pattern, right?) -
Second Place for GhostDoc in the Larkware Contest 2005!
[For my German readers: no, it’s not a mistake in the title – the first prize for GhostDoc means that I made the second place, as the first place gets the grand prize. I even googled it up, there doesn’t seem to be anything unusual about this usage of words]
[Everybody else: sorry, this is really not a joke, it’s confusing for us Germans and I had to explain it a couple of times today, including my parents on the phone]Okay, enough explanation, let’s get to the point: GhostDoc 1.9.0 (i.e. the Visual Studio 2005 version) made first prize (second place) in the Larkware contest 2005 and this means: I won stuff. Cool stuff. Oskar even emailed me and told me: “you won cool stuff!”. And lots of it. One little problem: somebody forgot to include the XXL package of extra time to try it all out ;-)
In related news, version 1.9.1 is in the works and should be out really soon. The new version will fix installation issues people had when their “My Documents” folder was moved to a network drive or share, and the problem that comments with a <see cref=”…” /> wouldn’t be generated in generic classes.
-
Code Snippet for Properties with Prefix Notation
As I wrote in previous blog posts, I still use prefix notation for private members, one reason being IntelliSense. If you’re like me, you may find these code snippets handy:
Name: Boolean Property Description: Code snippets for a boolean property. Shortcut: bp Result: private bool m_bMyProperty;public bool MyProperty
{
get { return m_bMyProperty;}
set { m_bMyProperty = value;}
}
Name: Integer Property Description: Code snippets for an integer property. Shortcut: ip Result: private int m_nMyProperty;public int MyProperty
{
get { return m_nMyProperty;}
set { m_nMyProperty = value;}
}
Name: Enum Property Description: Code snippets for an enum property. Shortcut: ep Result: private TheType m_eTheName;
public TheType TheName
{
get { return m_eTheName; }
set { m_eTheName = value; }
}
Name: Object Property Description: Code snippets for an object property. Shortcut: op Result: private TheType m_objTheName;public TheType TheName
{
get { return m_objTheName;}
set { m_objTheName = value;}
}Download: Properties.snippet -
Code Snippet for Debugger.Break()
Name: Debugger Break Description: Inserts a call of System.Diagnostics.Debugger.Break() Shortcut: brk Download: DebuggerBreak.snippet -
GhostDoc is one of "10 Must-Have Add-Ins" in MSDN Magazine
MSDN Magazine 12/2005: Visual Studio Add-Ins Every Developer Should Download Now
Wow… GhostDoc is one of them… I’d only wish the example would have been just a little bit more convincing (
SavePerson()-><summary>Saves the Person<summary>— hmm… ok…). But I must admit that it’s pretty tough to really show off GhostDoc’s features in only about a dozen sentences. I’d recommend you watch the video, or even better download and install GhostDoc. In case you’re impatient, the help file has a short chapter “How do I see some action without reading boring stuff?” ;-). -
GhostDoc 1.9.0 (for Visual Studio 2005) Released
The highly anticipated version of GhostDoc for Visual Studio 2005 has just been released (download on the GhostDoc homepage)
Originally I had planned to give it the version number 2.0, but for various reasons I couldn’t do much more than just porting version 1.3.0 (the most recent release for 2003) to Visual Studio 2005.
So the big feature is: GhostDoc 1.9.0 runs inside Visual Studio 2005 and the dialogs more or less match the style of the GUI (icons, general look). Unfortunately I didn’t have time to update the screenshots in the help file, but no functionality has changed so I’m pretty sure you can live with that ;-)
Umm… OK… one more thing: Anyone interested in VB.Net support? I’ve added what I call “experimental support”. In Visual Studio 2005, the CodeDOM for VB.Net now supports the DocComment property, so it was pretty easy to get this running in principle (some adjustments had to be done, though). But to be honest, I didn’t have the time (and experience in VB.Net) to test this enough to be an official feature of GhostDoc 1.9.0. So VB.Net support is turned off by default and you have to turn it on in the configuration dialog, on the “Options” tab. To the VB.Net developers out there: give it a try and tell me what you think. Oh, it would be very nice if somebody could port the demo project to VB.Net – the VB syntax keeps my head spinning… (sorry, I’m a curly braces guy since Turbo C 2.0).
By the way, this release is my entry for the Larkware 2005 Developer Tool Programming Contest; let’s see how things turn out for me and what the other competitors came up with.
-
GhostDoc Video is up on Channel 9
If you want a quick tour through GhostDoc in less than five minutes, check out the video.
It has already been posted on Channel 9 for a couple of days, but I was a bit reluctant to link to it as the first version posted was virtually useless. My original video was recoded by the Channel 9 staff, and in the process the texts in the Visual Studio source code editor window became completely unreadable. The second version is still slightly distorted, but the texts are readable and that's what matters in the end.
-
GhostDoc 1.3.0 Final Released
It took longer than expected, but the final of GhostDoc 1.3.0 has just been released (download on the GhostDoc homepage). Now that it’s out the door, I’m ready to move on to work on a VS2005 version.
What’s new in 1.3.0
Final compared to beta 2:
- Added: Some more "of the" trigger words and adjectives.
- Added: Command "RebuildDocumentation". It works like the "DocumentThis" command, but always creates the documentation from scratch. Note: The command was added pretty late in the release process; to minimize impact on the release date, it does not appear in any menu and can only be assigned to a hotkey via the Visual Studio options dialog.
- Added: Minor additions to the documentation.
1.3.0 beta 2 compared to beta 1:
- Added: New options for determining what should be the representation of the C# language keywords "true", "false" and "null" in a documentation comment.
- Added: New Macros $(True), $(False) and $(Null) to be used in text templates.
- Added: New Macros for the current date, the name of the current user, etc. ("environment macros").
- Added: New custom text that will be added once to a newly added documentation comment. As this text will not be updated, can be used for e.g. marking the date and time when a class member was added.
- Added: New summary template for default property rule (text generation was hard-coded in previous versions).
- Added: Template for methods with parameters for SingleWordMethodRule (text generation was hard-coded in previous versions).
- Added: Preliminary documentation for the dialogs.
- Changed: Default textual representation of "null", "true" and "false" back to the values of version 1.2.1 (<c>null</c>, <c>true</c> and <c>false</c>)
- Changed: Value text of the default property rule is no longer empty by default.
- Changed: Macros: Words.AsSentence -> Words.AllAsSentence
- Fixed: Various bugs related to customization features.
1.3.0 Beta 1 compared to 1.2.1:
- Added: New rules for using "inherited" documentation, including base class members and members of implemented interfaces. The inherited documentation will be cleaned from single <para> tags and the texts will be tweaked (e.g. when the summary for an interface method starts with "When implemented by a class....", and the summary is inherited by the method that is an implementation).
- Added: GhostDoc updates existing documentation. Empty tags (<summary>, <returns>, <param>) will be filled according to the generation rules, existing text remains unchanged. The update reorders the parameter documentation if the order of the parameter changes, and removes documentation for parameters that no longer exist.
- Added: User defined ("custom") rules using e.g. regular expressions for matching names and/or types.
- Added: New rule for "On..." methods -- no more "Ons the click" ;-)
- Added: Rule for static constructors.
- Added: Rule for the Finalize method (destructor syntax in C#).
- Added: Rule for event handler methods as they are created by the WinForms designer.
- Added: Rule for boolean properties.
- Added: Rules (both custom and built-in) can now be customized by editing templates that are used by the text generation rules.
- Added: Export of partial configurations is now possible (e.g. for exporting only a single custom rule).
- Changed: Summary text of the default constructor rule is now 'Initializes a new instance of the <see cref="ClassName" /> class.', i.e. uses the wording in the Microsoft documentation. The old "Creates a new <see cref="ClassName" /> instance" is debatable - is it the constructor that actually creates the instance, or is the constructor called when the instance is created? Thus the Microsoft wording is preferable.
- Changed: The configuration is now stored in the ApplicationData\Weigelt\GhostDoc directory. Old configurations in the installation directory (versions before 1.3.0) will be upgraded and stored in the new location.
- Fixed: <returns> tag no longer disappears if the return type is an array.
- Fixed: Overall handling of array types.
-
Paint Shop Pro X : Solution for Weird Screenshot Colors
I’ve been using various versions of Paint Shop Pro for a couple of years now; virtually every bitmap I need when developing software (either for the GUI or the documentation) has at some point been touched by this program. I just bought version 10 (upgrading from version 9) and encountered a problem that was pretty confusing at first: A simple screenshot (taken using [Ctrl-]PrtScr), appeared with distorted colors when being pasted into Paint Shop Pro X.
It took me some time to figure this out, so just in case somebody else has the same problem: In version 10, Paint Shop Pro has a new “color management” feature that is enabled by default. If you don’t need that feature and just want to work like you have done with earlier versions, the simplest solution is to switch it off via “File” -> “Color Management” -> “Color Management” dialog -> Uncheck “Enable Color Management”.
I’m sure that the color management is a really useful feature (for those who need it), but the “out-of-the-box experience” for somebody like me (whose first thought after setup wasn’t exactly “gee, I really need to calibrate my monitor now”) has been a bit confusing.
P.S. Just out of curiosity, I calibrated my monitor (“File” -> “Color Management” -> “Monitor Calibration”). Needless to say, even without spending much time, things look much better (but I’ll keep color management off anyway ;-).
-
PDC 05: WPF (aka "Avalon") - Wow, I am impressed...
Data binding everywhere (every control, every property bindable), data templates (that can also be changed on the fly, depending on e.g. the value of a certain property) – I just saw virtually all my GUI problems of the last years solved. Okay, there will be new problems, but this is such a huge step forward… impressive.
-
PDC 05: See GhostDoc at the "Show Off" Session
-
PDC 05: Monospaced fonts everywhere :-(
In the sessions I’ve been so far, each time code is shown on the screen, it’s in some monospaced font. Either “Lucida Console” (which is kind of ok), or worse “Courier New” (by the way: am I really the only person on the planet to notice that this font doesn’t scale well? It sucks on high-resolution laser printers, and it’s not that great on-screen in sizes larger than say 12pt).
Anyway, if we’d still be programming with C-style function names, I wouldn’t complain. But now that Microsoft advocates long identifier names for years, and the Framework libraries making heavy use of long and descriptive names (and I’m all for that!), why is it that everybody still thinks that code needs to be in monospaced font, even if it means that some identifier names span several meters on the projection screens?
-
Microsoft Campus Tour
Today was the day: the day of the Microsoft Campus tour which was a prize for winning Roy Osherove’s Visual Studio add-in last year (read here).
from left to right: my colleague Jochen Manns, Keen Brown (MS),
me, my other colleague Sascha LehmannI’d like to thank Keen (who filled in for Josh) and Sara – it was a fun day!
The things that amazed me the most: the size of the campus and the speed at which Sara talks ;-)
-
GhostDoc - The Movie ;-)
I just submitted my video for the PDC 05 “Show Off” session. Producing this video was much more work than I expected, which means that I won’t be able to release the final of 1.3.0 before the PDC (I’m already leaving on Thursday, as I’ll take a little detour on my way to L.A).
The hardest part of the video was speaking English and presenting GhostDoc – either I mis-pronounced a word or stumbled over a wicked combination of “s” and “th” (which I wouldn’t care about in a real-life situation), or I made a mistake during the presentation. Fortunately with some editing, many things can be fixed.
If the video is accepted, it will be shown at the “Show off” session and will be made available after the PDC. Sorry, I can’t post a download link before the PDC.Update: The video was accepted and shown at the PDC, and is now up on Channel 9.
-
GhostDoc 1.3.0 Beta 2 Released
Beta 2 of GhostDoc 1.3.0 has been released, which in terms of features should be pretty close to the release version. The documentation has made a major step forward, but stills needs some work (proofreading, more and better Howtos, especially tutorials for defining custom rules).
What’s new in 1.3.0 beta 2 compared to beta 1:
- Added: New options for determining what should be the representation of the C# language keywords "true", "false" and "null" in a documentation comment.
- Added: New Macros $(True), $(False) and $(Null) to be used in text templates.
- Added: New Macros for the current date, the name of the current user, etc. ("environment macros").
- Added: New custom text that will be added once to a newly added documentation comment. As this text will not be updated, can be used for e.g. marking the date and time when a class member was added.
- Added: New summary template for default property rule (text generation was hard-coded in previous versions).
- Added: Template for methods with parameters for SingleWordMethodRule (text generation was hard-coded in previous versions).
- Added: Preliminary documentation for the dialogs.
- Changed: Default textual representation of "null", "true" and "false" back to the values of version 1.2.1 (<c>null</c>, <c>true</c> and <c>false</c>)
- Changed: Value text of the default property rule is no longer empty by default.
- Changed: Macros: Words.AsSentence -> Words.AllAsSentence
- Fixed: Various bugs related to customization features.
For those who missed the release of beta 1 and still work with 1.2.1:
1.3.0 Beta 1 compared to 1.2.1:
- Added: New rules for using "inherited" documentation, including base class members and members of implemented interfaces. The inherited documentation will be cleaned from single <para> tags and the texts will be tweaked (e.g. when the summary for an interface method starts with "When implemented by a class....", and the summary is inherited by the method that is an implementation).
- Added: GhostDoc updates existing documentation. Empty tags (<summary>, <returns>, <param>) will be filled according to the generation rules, existing text remains unchanged. The update reorders the parameter documentation if the order of the parameter changes, and removes documentation for parameters that no longer exist.
- Added: User defined ("custom") rules using e.g. regular expressions for matching names and/or types.
- Added: New rule for "On..." methods -- no more "Ons the click" ;-)
- Added: Rule for static constructors.
- Added: Rule for the Finalize method (destructor syntax in C#).
- Added: Rule for event handler methods as they are created by the WinForms designer.
- Added: Rule for boolean properties.
- Added: Rules (both custom and built-in) can now be customized by editing templates that are used by the text generation rules.
- Added: Export of partial configurations is now possible (e.g. for exporting only a single custom rule).
- Changed: Summary text of the default constructor rule is now 'Initializes a new instance of the <see cref="ClassName" /> class.', i.e. uses the wording in the Microsoft documentation. The old "Creates a new <see cref="ClassName" /> instance" is debatable - is it the constructor that actually creates the instance, or is the constructor called when the instance is created? Thus the Microsoft wording is preferrable.
- Changed: The configuration is now stored in the ApplicationData\Weigelt\GhostDoc directory. Old configurations in the installation directory (versions before 1.3.0) will be upgraded and stored in the new location.
- Fixed: <returns> tag no longer disappears if the return type is an array.
- Fixed: Overall handling of array types.
FAQ
- When is the final coming out?
Before the PDC. - What about VS2005 support?
After the PDC.
-
"Show Off" at PDC 2005 ?
Michael Swanson writes: “Show Off at PDC 2005”:
We propose a PDC 2005 2-hour session called Show Off. The concept: "Why demo your cool application to a few friends, when you can Show Off to thousands of your peers at the PDC?" […] You and/or your team put together a single WMV file that shows off something cool about your application, tool, technique (or whatever). […] Videos are limited to 5 minutes. […] So, what do you think? Would you participate? We're trying to gauge interest before we spend a bunch of time on this.I think that’s a good idea. Hey, I’m actually thinking about making my own video (guess about what ;-), even though I’m not quite sure how speaking English in front of a camera works out for me – but I’d give it a try…
-
GhostDoc 1.3.0 Beta 1 Released
I’m pleased to announce that beta 1 of GhostDoc 1.3.0 has been released. A big “Thank You” to the steadily growing number of testers who helped me testing a couple of preview builds, pointed out a few minor issues and gave me an overall “Thumbs up”.
What’s New
- New: New rules for using "inherited" documentation, including base class members and members of implemented interfaces. The inherited documentation will be cleaned from single <para> tags and the texts will be tweaked (e.g. when the summar for an interface method starts with "When implemented by a class....", and the summary is inherited by the method that is an implementation).
- New: GhostDoc updates existing documentation. Empty tags (<summary>, <returns>, <param>) will be filled according to the generation rules, existing text remains unchanged. The update reorders the parameter documentation if the order of the parameter changes, and removes documentation for parameters that no longer exist.
- New: User defined ("custom") rules using e.g. regular expressions for matching names and/or types.
- New: New rule for "On..." methods -- no more "Ons the click" ;-)
- New: Rule for static constructors.
- New: Rule for the Finalize method (descructor syntax in C#).
- New: Rule for event handler methods as they are created by the WinForms designer.
- New: Rule for boolean properties.
- New: Rules (both custom and built-in) can now be customized by editing templates that are used by the text generation rules.
- New: Export of partial configurations is now possible (e.g. for exporting only a single custom rule).
What’s Missing
There are a couple of small features I’d like to see in 1.3.0 final. And then there’s a huge update of the help file waiting to be done.
FAQ
- When is the final coming out?
My personal deadline is end of August. - What about VS2005 support?
I guess i’ll wait for the PDC bits of VS2005
-
GhostDoc: Looking for Testers
I’m planning a first public beta of GhostDoc 1.3.0 towards the end of July. A couple of private builds have already been released to colleagues and people on the net who offered their help. So far feedback has been pretty good. People like the new features, some issues have been found, most of them could be fixed in the following builds.
Now I would like to have a couple more people to test the current build. If you’re interested, contact me via the contact form. Please tell me about your system (e.g. which other Add-ins are installed), since when you have been using GhostDoc and how often you use it. I’ll then send you an email with the download link (when waiting for a reply, please take time zone differences into account ;-).
Here are the new features you can try out in the preview:
- New rules for using "inherited" documentation, including base class members and members of implemented interfaces. The inherited documentation will be cleaned from single <para> tags and the texts will be tweaked (e.g. when the summary for an interface method starts with "When implemented by a class....", and the summary is inherited by the method that is actually the implementation).
- GhostDoc now updates existing documentation. Empty tags (<summary>, <returns>, <param>) will be filled according to the generation rules, existing text remains unchanged. The update reorders the parameter documentation if the order of the parameter changes, and removes documentation for parameters that no longer exist.
- User defined ("custom") rules using e.g. regular expressions for matching names and/or types.
- New rule for "On..." methods -- no more "Ons the click" ;-)
- Rule for static constructors.
- Rule for the Finalize method (destructor syntax in C#).
- Rule for event handler methods as they are created by the WinForms designer.
- Rule for boolean properties.
- Rules (both custom and built-in) can now be customized by editing templates that are used by the text generation rules.
A few words about the quality of this preview: Answering the obvious question “does it fry my data and/or my Visual Studio installation?”, I can say that the Visual Studio integration and installation/uninstallation are at least as good as in version 1.2.1, so I wouldn’t hesitate to run the setup on production machines. The current problems are mostly missing features, some usability issues and the online help that hasn’t been updated yet.
-
Two Years of Blogging
Oops, so I missed my blog’s anniversary (by a day). My first entry was on July, 2nd 2003 and it’s incredible how fast the time has passed. A lot has happened since the last anniversary – most of it could be summarized into one word: GhostDoc. After my articles about Visual Inheritance, this little add-in has put me high up on Google. Right now I’m still working on version 1.3.0 which is pretty late as I’m not working on it in the same frantic pace as for 1.0.0 (which got ready 11 minutes before the deadline).
But this year hasn’t been only about GhostDoc. Other blog posts – besides the occasional rant – included:
- LinkBox - Fun with Panels, LinkLabels and AutoScroll
- Splitter Control with Drag Handle
- ReadOnlyRichTextBox
- LastBoxStanding (a Windows service that pings a configurable list of machines in your LAN to determine whether at least one of them is still running. If no machine responds, the service performs a custom action, e.g. a shutdown.)
Let's see what the next year brings…
-
PDC 05: I'll be there / GhostDoc goes Redmond
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.
-
Cool: Bold Fonts in Visual Studio 2005's Text Editor
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!)
- When you start typing, the keyword is not complete and thus the “publi” is rendered as normal text:
-
LinkBox - Fun with Panels, LinkLabels and AutoScroll
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. -
"Visual Studio Hacks" Book: Excerpts Online
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.
-
GhostDoc News
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.
-
My Copy of "Visual Studio Hacks" Has Arrived
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).
-
A GhostDoc Feature I Will Not Implement
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?
-
Why throwing an exception should be the exception
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.
-
Sound Forge 8.0 Scripting
One of my other hobbies besides developing software is audio editing. Working with Sound Forge for a couple of years now, I just upgraded to Sound Forge 8.0. Scripting is one of the new features and while it has a certain “version 1.0” feeling to it, it’s nice to see the preferred choice of “scripting language”:
-
LastBoxStanding 0.9.1 (bugfix release)
-
LastBoxStanding 0.9.0
Summary: LastBoxStanding is a Windows service that pings a configurable list of machines in your LAN to determine whether at least one of them is still running. If no machine responds, the service performs a custom action, e.g. a shutdown.
Some time ago I built a server for my LAN from old parts (e.g. a P2B mainboard with a PII 400 and some RAM I had in a drawer). I use it for storing backup images and running SourceGear Vault (source control) and Dragnet (bug tracking) mainly used for my GhostDoc project. The server is not connected to a monitor and it’s really quiet (thanks to some hard-core silent modding), so it’s not uncommon that I simply forget to shut it down before going to bed. That usually means that the server keeps running until I come back from work the next evening – what a waste of electricity.
I solved the problem by writing a Windows service to shut down the server automatically when it’s no longer needed, which is defined as when no other potential client on the LAN is running. The current version of LastBoxStanding can be configured to call any executable when the computer running the service is “the last box standing”.
You can download the most recent version on the LastBoxStanding homepage.
Update: Unfortunately, a small issue with 0.9.0 was found. If you set the check interval on your server to say 5 minutes, (re)start the service and then switch off all other machines on the LAN, LastBoxStanding does not perform the shutdown (or any other action you have configured). This is because the service has to reach at least one of the configured clients once and – this is the problem – the first check is not performed when the service starts, but after the (timer) interval has elapsed. If at that time none of the machines can be reached, LastBoxStanding assumes that the server is running standalone (e.g. for maintenance) where you don’t want the automatic shutdown.
Even if this issue does not affect usage in “Real Life” that much, it’s a huge problem if people download LastBoxStanding and want to try it out. I’ll look into providing a fix this evening when I get back from work.
-
GhostDoc in Upcoming Book "Visual Studio Hacks" by James Avery
Ok, now that the book “Visual Studio Hacks” by James Avery has been announced officially, I’m finally allowed to talk about my (small) contribution to the book: My Visual Studio add-in GhostDoc is one of the “hacks”.
Shortly after GhostDoc won Roy Osherove’s Add-In contest in August 2004, James contacted me to write a quick run-down on using GhostDoc. He couldn’t offer any money (if you wonder why, you should read this), but hey – a few hours work for a free book isn’t too bad ;-)
Let’s see what the editors at O’Reilly thought of my English writing skills (or lack thereof?) and what’s left of my original text…
-
Raising C# events doesn't feel right (and seems to have problems too)
[This blog post was inspired by reading “Events, Delegate and Multithreading” by Brad Abrams.]
I'm pretty sure the language designers thought about the whole thing way longer than I did, but from the very beginning raising events simply didn't "feel right". I’m not talking about the pattern of using “On…” methods — while that was something I (with an extensive Javascript background) had to get used to, it was a typical case of “what? whose idea was that? hmm, that’s not so dumb after all… hey, good idea!”.
No, it’s the way of actually raising the event inside the “On…” method. In the blog post mention above Eric Gunnerson is quoted “We have talked about adding an Invoke() keyword to the language to make this easier, but after a fair bit of discussion, we decided that we couldn't do the right thing all the time, so we elected not to do anything”. Well, but that’s exactly what I’m missing: a keyword. While I don’t miss much from VB6 (ok, maybe the command window), I really miss the good ol’ RaiseEvent.
When you look at source code, keywords are something that catch your eye. While you are bombarded with lots and lots of words (names of classes, variables, methods, etc. ), keywords like “delegate”, “event”, “throw”, “override” (man, I’m thankful for that one!) stand out — not only because of the coloring inside the editor, but also because of the different syntax compared to lines and lines of “variable = Method(parameter)”.
For example throwing an exception:
throw new FooException("bar");It says “throw” and you can virtually see some referees throwing a yellow flag.
If I declare a delegate “FooHandler” and an event "Foo"
public delegate void FooHandler(object sender, FooArgs e);
public event FooHandler Foo;then one can argue the overall approach (is it too complicated yes/no?), but nevertheless it’s quite clear what the code is trying to tell me: This is a delegate, and this is an event, and there seems to be some connection between those two (because FooHandler appears in both).
But then comes the big letdown: the code for raising the event. Until recently I would have used
protected virtual void OnFoo(FooArgs e)
{
if (Foo != null)
Foo(this, e);
}Now I’ve read the recommendation to use
protected virtual void OnFoo(FooArgs e)
{
FooHandler handler = Foo;
if (handler != null)
handler(this, e);
}Sorry, but this doesn’t survive my personal test for “is the important stuff easily discoverable”: Step back from the monitor, squint your eyes until things look kind of blurry, and then collect all information you can get from what you see with a quick look. For fun, try it with the code example. While “throw new blah blah” and “public event blah blah blah” give you a rough idea of what’s happening, you have to look again to find out what “protected virtual blah handler handler blah handler null blah this” is all about. To avoid misunderstandings: This is not about understanding a programming language without learning it. What I’m talking about is browsing code really fast, looking at each line only fractions of a second, and not actually thinking about the code, but just matching some basic patterns inside your brain — stuff we’re all doing automatically when scrolling up and down while editing text.
Ok, this post is longer than it should be, so let’s cut this whole thing short and get to the point:
Comparing raising an event with the way how to throw an exception, and keeping in mind that the official wording (according to the Design Guidelines for Class Library Developers) is that exceptions are "thrown" and events are "raised", I would personally prefer:
protected virtual void OnFoo(FooArgs e)
{
raise Foo(this, e);
}What should the “raise” keyword do internally? Let me play the role of the unfair customer here: I don’t care, just make it work. I want to raise an event and that should work without the danger of a race condition or whatever.
-
GhostDoc News
As mentioned on the GhostDoc homepage (which I use for the smaller status reports that also contain more private stuff), I’m back working on version 1.3.0. Since Christmas I have managed to spend a good amount of time on GhostDoc, but things are not progressing as fast as I had hoped. There are a couple of tough problems to solve that come with one of the major goals for 1.3.0: User-defined rules.
In addition to user-customizable rules as mentioned in a previous post, it will be possible to define new rules by specifying regular expressions for matching e.g. method signatures, and templates containing macros for generating documentation texts. This may not be as flexible as writing new rules in C# code (which will have to wait until the framework has been stabilized), but there’s a lot that can be done with this simple solution.
Things like upgrading from earlier versions (without losing customizations) and synchronizing configuration files between installations e.g. at home and at work turn out to be pretty tricky even though these topics already have been addressed in previous versions. Right now I’m busy refactoring and extending the code for reading/writing/importing/upgrading/merging configuration files, and hey — my existing unit tests actually caught a couple of nasty bugs and thus saved me a lot of time!
To finish this post, here’s a screenshot showing the rule configuration tree (no new rules shown here, though):
I’m far away from any release, which in turn is a chance for your suggestions and feature requests to be included in 1.3.0. Simply drop me a line in an email (ghostdoc at roland-weigelt.de).
