Selfelected

Xml comment check

In C#/VBNet there is a nifty thing called Xml comments.  I always use it to explain my methods and classes.  A good thing about Xml comments is that they pop up as intellisense.  Press ctrl-J in Visual studio at your method call and your comments are shown.  The comments survive project boundaries so your well crafted comments in the business layer pop up at the presentation method calls to aid the GUI programmers.

The comments don’t travel C#->VBNet though.

In VBNet you get squiggly lines when the method call and the Xml comment don’t match.  In C# you have to go through the Analyze->Run code analysis to get the differences.

There are more comments on commenting here and here.

truefalse

Personally I write xml comments on all my methods even though I am a fan of method names  enough describing that comments really are unnecessary.  By descriptive method names I mean that others also understand them.

In a project I stumbled upon this method:

private void ShowHideControl( bool truefalse ){…

Since I had the source code it didn’t take much effort to find out what it did.

But a question remains – how do I present the problem for the original programmer without being rude?

A tip for writing Xml comments in Csharp

There is something called xml comments in the dotnet world.

It looks something like

/// <summary>
///
/// </summary>
/// <param name=”name”></param>
/// <returns></returns>
public User FindUser( string name )
{…

The trick here is to write the comments on the very first line. Like:

/// <summary>This method finds and returns a User by its name.
/// </summary>
/// <param name=”name”></param>
/// <returns></returns>
public User FindUser( string name )
{…

When the code is folded it then looks like

/// <summary>This method finds and returns a User by its name. …
public User FindUser( string name )…

Visual Studio “suggests” writing the comments on line two, like

/// <summary>
/// This method finds and returns a User by its name.
/// </summary>
/// <param name=”name”></param>
/// <returns></returns>
public User FindUser( string name )
{…

but then after folding it looks like

/// <summary> …
public User FindUser( string name )…

(this is not a problem in vbnet)

More commenting comments are found here and here.

Sortable IBindinglist

Datagridviews in dotnet work well with datasets.  They work less good with “normal” objects; for instance sorting is much more of a hassle to implement.

The sorting problem is solved nicely in this http://groups.google.co.uk/group/microsoft.public.dotnet.languages.csharp/msg/2b7528c689f9ef84 piece of code.  It is more or less just to copy the code and violà, a sortable object list.

Change the name of splitContainer1

Dotnet WinForm has a control called Split container.  It is a nice control for making forms scale properly when the user changes their sizes.

Now there is a bug in Vsnet that surfaces when you put split containers in each other and do not change their default names.  splitContainer1, splitContainer2 etc.

The remedy is easy: change the name as you create the split containers.

Update:
The bug reveals itself by stopping the designer from rendering the form; instead a text like “a control cannot be in itself” shows.
If that happens you are not totally screwed even though there is no clue to what to do.

Open the .designer file and remove a split control. I have no idea of how to find out which split control messed up. Just remove one. Open the graphical designer (possibly close and open). Repeat until you have a form like usual but the controls you have put on the split controls are gone. Don’t dispair, they are not gone – they are just not placed anywhere.

Drop a split control on the graphical designer. Add controls to it through myListbox.Controls.Add( myTextbox )…. If you do it properly – like adding the right controls to the correct new split control everything is like before. Except possibly event handlers om the split controls. At least you didn’t have to remake the whole form.

How to write xml comments in c#

My prefered way to write XML comments in C# is to write the first sentence on the first row like this:

/// <summary>This method does nothing.
/// <summary/>
public void Foo()
{
//NOP.
}

because when one folds the code (ctrl-m-o) one can see the first row like this:

/// This method does nothing. …
public void Foo() …

This is not an issue in vbnet.

To create a document out of this use Sandcastle which takes over after nDoc which is discontinued.

More comments on commenting are found here and here.