2

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

Improve this question
7
  • 1
    I would simply change this to an automatic property public bool DoILookGood { get; set; }. Commented Dec 26, 2011 at 13:11
  • 1
    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. Commented Dec 26, 2011 at 13:15
  • 4
    Yes, I know ;-) I would strongly vote for not commenting the private field, but only the public property. Commented Dec 26, 2011 at 13:26
  • 1
    @Marc: Btw, you can have also public getter and private setter for automatic properties. `public bool MyBool { get; private set; } Commented Dec 26, 2011 at 13:42
  • 1
    @Marc: np :) I hear this a lot. So maybe you want to take a look at the list of c# language features. Commented Dec 26, 2011 at 13:56

1 Answer 1

Reset to default
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).

Improve this answer
Sign up to request clarification or add additional context in comments.

3 Comments

OK I see, but with <see cref="MyVariable"> i am not getting a tooltip showing me the comment-text from the public property ?
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.
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 :-)

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.