Documentation Comment Creation

Documentation Comment Creation

One of the most painful points about coding in VB.NET is the time taken to compile projects.  Luckily the background compilation more than compensates for this as you don’t need to compile your application in order to see all the compilation errors in your code. Interestingly one of the key artifacts of a slower compilation process is that you typically want to reduce the amount of unnecessarily tasks that are carried out as part of compilation. 

Of particular note is the generation of XML documentation files.  I’m not for one minute suggesting that their creation isn’t important but you don’t need to create them during debugging.  To disable the creation of these files during debug mode go into the project properties dialog for each project, make sure the Configuration is set to Debug (which is probably the Active configuration type) and then disable the XML documentation.

image

C# Project Settings

image 

VB.NET Project Settings

Interestingly by default this option is enabled for VB.NET projects, yet disabled for C# projects – perhaps this says something about the different styles of developers. One gotcha for VB.NET Developers is that disabling this option does more than simply preventing the creation of the XML documentation file.  It also prevents the automatic creation of XML documentation comments.

For example if you were to document the following property:

image

you would place the cursor on the line before the Public keyword and press ”’ (/// has the equivalent behaviour in C#).  This would automatically generate a commented XML snippet:

image

Unfortunately in VB.NET if you disable the generation of XML documentation files you are also disabling this functionality – you can press ”’ as many times as you want but nothing will happen.  For C# developers there is a checkbox that controls the creation of documentation comments in the Options dialog:

image

Leave a Reply

Your email address will not be published. Required fields are marked *