C# commenting technique / reuse of comments

Question

i am generally declaring fields in a class as a private field together with a public property which accesses this field from outside (nothing spectacular so far smile):

private bool doILookGood;

public bool DoILookGood
{
   get { return doILookGood; }
   set { doILookGood = value; }
}

Now I was wondering if there's an elegant and efficient way to comment this situation without writing the same comment twice. In other words i want to retain the functionality that the IDE is showing me a variables comment while mouse-hovering with a tooltip.

So far i am commenting in this way:

/// <summary>
/// This i always true.
/// </summary>
private bool doILookGood;

/// <summary>
/// This i always true.
/// </summary>
public bool DoILookGood
{
   get { return doILookGood; }
   set { doILookGood = value; }
}

and I want to have something like this:

/// <summary>
/// This i always true.
/// </summary>
private bool doILookGood;

/// <summary cref="doILookGood" />
public bool DoILookGood
{
   get { return doILookGood; }
   set { doILookGood = value; }
}

I know that using XML tags for commenting private fields is not very meaningful because they don't show up in the generated doc but again i only want to have (IDE-internal) comment-tooltips.

Maybe someone has a clue :)

I would simply change this to an automatic property `public bool DoILookGood { get; set; }`. — Uwe Keim, Dec 26 '11 at 13:11
Hi and thank you for your quick reply :) That would be the obvious solution but in some situation i need the distinction between the private field and the public getter/setter property. — marc wellman, Dec 26 '11 at 13:15
Yes, I know ;-) I would strongly vote for _not_ commenting the private field, but only the public property. — Uwe Keim, Dec 26 '11 at 13:26
@Marc: Btw, you can have also public getter and private setter for automatic properties. `public bool MyBool { get; private set; } — Matthias, Dec 26 '11 at 13:42
@Matthias: That's a cool feature, i've never heard of that before - I guess this is very useful when regulating the access of a field inside the boundaries of a class scope - but i am not quite sure whether i can use it to solve my issue. Anyways **Thank you very much** for this excellent tip! :) — marc wellman, Dec 26 '11 at 13:53
@Marc: np :) I hear this a lot. So maybe you want to take a look at the list of [c# language features](http://stackoverflow.com/questions/9033/hidden-features-of-c). — Matthias, Dec 26 '11 at 13:56

ken2k · Accepted Answer · 2011-12-26T13:34:20.773

6

Use auto-properties as much as possible. This will avoid the use of a private member when not required.

public bool DoILookGood { get; set; }

If it's not possible (for instance when implementing INotifyPropertyChanged), here's how I deal with it (please note it's just for the example, I would definitely use auto-properties instead of the code below):

    /// <summary>
    /// Private member for <see cref="MyValue"/>.
    /// </summary>
    private bool myValue;

    /// <summary>
    /// Gets or sets a value indicating whether ...
    /// </summary>
    /// <value>
    ///   <c>true</c> if ...; otherwise, <c>false</c>.
    /// </value>
    public bool MyValue
    {
        get { return this.myValue; }
        set { this.myValue = value; }
    }

EDIT: I also recommend using GhostDoc to save time (a plugin that is able to automatically generate comments).

edited Dec 26 '11 at 13:34

answered Dec 26 '11 at 13:15

ken2k

48,145
10
116
176

OK I see, but with **** i am not getting a tooltip showing me the comment-text from the public property ? – marc wellman Dec 26 '11 at 13:21
Nope you won't, but you can navigate to the property if you have third party plugins installed (resharper for instance). Anyway, I don't think the whole information about the property should be copied for the associated private members. Private members of properties are here because they are required, but the developer must not use them outside the scope of the property itself. So the only thing the developer should know is the associated property name. – ken2k Dec 26 '11 at 13:25
OK I will try to reduce my need to document private members :) and for those i have to i will have a look at third-party tools (including GhostDoc). I just thought there's an obvious "work-around" for this public/private scenario that everyone knows except me :) ... Thank you very much :-) – marc wellman Dec 26 '11 at 13:30

C# commenting technique / reuse of comments

1 Answers1