May
26
2009
Been a fan for a long time now, but thought I would post about this valuable tool for your Visual Studio arsenal.
Ronald Weigelt publish GhostDoc back in 2003. It was around the time that NDoc got a lot of attention and code comments once again became chic… Basically, GhostDoc is a Visual Studio add-in which;
“automatically generates XML documentation comments for C#.”
It is as simple as a Ctrl+Shift+D within a method, class, etc. and magic, you have comments. It is very intuitive as far as its dictionary and generated text, it will even pull the exact comments from inherited and overridden classes/ methods.
One interesting piece of this tool assists with your coding adventures is if the generated comments read, well a little funny, then there is a good chance that your naming is a little vague and you may want to think about clarifying the class/ method/ or property you are commenting… Here is an example of what I am talking about;
/// <summary>
/// Handles the Click event of the EditNoteButton control.
/// </summary>
/// <param name="sender">The source of the event.</param>
/// <param name="e">The <see cref="System.EventArgs"/> instance containing the event data.</param>
protected void EditNoteButton_Click(object sender, EventArgs e)
{
}
Fairly simple and straight forward. The above comments were created entirely from GhostDoc…
One of the scenarios where it helps you with naming is when things look strange after creating the comments.
/// <summary>
/// Gets or sets a value indicating whether [logged in].
/// </summary>
/// <value><c>true</c> if [logged in]; otherwise, <c>false</c>.</value>
public bool LoggedIn { get; set; }
Now that may work, maybe not a great example, but look what happens to the comments if we alter the property name a little.
/// <summary>
/// Gets or sets a value indicating whether this instance is logged in.
/// </summary>
/// <value>
/// <c>true</c> if this instance is logged in; otherwise, <c>false</c>.
/// </value>
public bool IsLoggedIn { get; set; }
Not a fantastic example, yet you should get the point that slight changes can affect the outcome of your comments and allow for you to be a little more explicit in naming.
If anything, it is most certainly worth some daily entertainment. Check out the Hall of Shame, where users post the sometimes funky examples of the automatically generated comments.
/// <summary>
/// Ases the enumerable.
/// </summary>
/// <param name="reader">The reader.</param>
/// <returns></returns>
public static IEnumerable<DataRecord> AsEnumerable(this DbDataReader reader)
Not a perfect science, but certainly a tool which greatly simplifies and obligatory and sometime monotonous developer responsibility.
Check it out, well worth it, a great time saver and proven to provide occasional mild entertainment… Roland Weigelt's GhostDoc!
Enjoy!
RA