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? :)

 

 

This entry was posted in Uncategorized. Bookmark the permalink. Follow any comments here with the RSS feed for this post.

13 Responses to When GhostDoc goes Bad

  1. Hex says:

    Some people just can’t let go of the hungarian notation concept. Completely oblivious of the attempt to move programming closer and closer to human / intuative language. These are usually the last ones to let go of hungarian notation. “m_” does that really help anyone understand what this is anymore than just the variable name? who writes methods complex enough that a distinction is neccessary? Just procedural programmers, I assure you.

  2. anonymous ghost doc user says:

    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

  3. Bil Simser says:

    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.

  4. Greg says:

    LMAO that is brilliant for those searching its http://ghostdoc.12.forumer.com/viewforum.php?f=7&sid=3750011d3982e68d0cd6db7672d20b7f

    I agree 100% per well written comments :)

  5. John Rayner says:

    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:
    ///

    /// Ensures the ready for save.
    ///

    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.

  6. Ghostdoc says:

    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.

  7. sergiopereira says:

    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.

  8. Greg says:

    DaRage this would be OK without the underscores to you?

  9. DaRage says:

    underscores!!!! ugh!!

  10. Greg says:

    *says the guilty until proven innocent*

  11. The underscore before variable names normally drives me mad, but before parameters is just crazy. Who does that?

  12. JD says:

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

  13. anonymous ghost doc user says:

    ur a jerk greg

Leave a Reply

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

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>