CodeBetter.Com
CodeBetter.Com
RSS 2.0 via Feedburner
           Do you Twitter? Follow us @CodeBetter

Greg Young [MVP]


When GhostDoc goes Bad

The problem with tools like GhostDoc is that you have to use them to remove the tedious bits of documentation, not consider what they produce to be ok as documentation

I actually came across this today:

 

   44 /// <summary>

   45 /// Initializes a new instance of the <see cref="UpdateOrderPriceCommand"/> class.

   46 /// </summary>

   47 /// <param name="_Gateway">The _ exchange gateway.</param>

   48 /// <param name="_Symbol">The _ symbol.</param>

   49 /// <param name="_BrokerNumber">The _ broker number.</param>

   50 /// <param name="_OrderNumber">The _ order number.</param>

   51 /// <param name="_PriorityTimeStamp">The _ priority time stamp.</param>

   52 /// <param name="_Price">The _ price.</param>

   53 public UpdateOrderPriceCommand(ExchangeGateway _Gateway, string _Symbol,

   54     int? _BrokerNumber, string _OrderNumber, DateTime? _PriorityTimeStamp, decimal? _Price)

   55 {

 

So is that price per share or price for all of the shares? :)


 

 



Comments

JD said:

don't worry nobody read's greg's blogs with that scary mug up there.

# December 4, 2007 6:02 PM

Maruis Marais said:

The underscore before variable names normally drives me mad, but before parameters is just crazy. Who does that?
# December 4, 2007 9:40 PM

Greg said:

*says the guilty until proven innocent*

# December 4, 2007 9:42 PM

DaRage said:

underscores!!!! ugh!!
# December 4, 2007 10:01 PM

Greg said:

DaRage this would be OK without the underscores to you?

# December 4, 2007 10:10 PM

sergiopereira said:

I find these auto-generated comments almost completely useless. If your API is clear enough to produce readable ghostdoc output, you probably don't need xml comments that much.
# December 4, 2007 10:44 PM

Ghostdoc said:

Let me know when Ghostdoc goes good. Honestly, what's the point of generated comments? Anything generated by a computer can be generated in my head. At least that way I won't waste time reading the doc thinking there might actually be something useful in there.

# December 5, 2007 8:30 AM

John Rayner said:

We have a wiki page of "GhostDoc top ten" where we list stupidly generated comments that people have checked in.  It's quite amusing.  The funniest / saddest one right now is:

       /// <summary>

       /// Ensures the ready for save.

       /// </summary>

       void EnsureReadyForSave();

My project mandates the use of code comments.  Mostly as a reaction to that, people have adopted GhostDoc.  However, I do think that a well-written code comment is very useful - mostly because it's shown along with the Intellisense in Visual Studio.

# December 6, 2007 5:19 PM

Greg said:

LMAO that is brilliant for those searching its ghostdoc.12.forumer.com/viewforum.php

I agree 100% per well written comments :)

# December 6, 2007 5:33 PM

Bil Simser said:

Yeah, except that I would never write or allow code like this to be written. Underscores on method parameters? Never. If we ever use underscores (and they make sense) it would indicate a field on a class so this scenario would never happen. In any case, Roland should update his tool to deal with this (if anything can go wrong, prevent it) but if someone came to me with this I would tell them to rename the parameters and stop wasting my time.
# December 6, 2007 10:38 PM

anonymous ghost doc user said:

I love the Underscores and have been using it as a convention for a long time,

method params "_"

private members "m_"

public CamelCase

private to scope of method first letter lowercase rest camelcase.

Allows me to look at any member and know where it came from in a glance

Now I know that may not be standard but I like it and use cause it allows me identify very quickly where things are coming from

# December 7, 2007 12:47 PM

Leave a Comment

(required)  
(optional)
(required)  

Enter the numbers above:
Add
Check out Devlicio.us!