Summarize properties with same accessors

[proepkes]

Is:

class Class {
  public bool A { get; set; }
  public bool B { get; set; }
  public bool C { get; set; }
 ...
}

Want:

class Class {
  public bool A, B, C { get; set; }
 ...
}

[Pretasoc]

How would xml comments on those properties work?

[MV10]

I can't agree with this.

I understand the appeal, but I recently had to refactor a bunch of code that a VB6 guy wrote almost 20 years ago which declared variables like int a, b, c (which I remember being common in VB, but doesn't seem to be in common use now, unless VB.NET still does it?) and the minute one of those doesn't match the pattern, you're going to have a Very Bad Day.

[DavidArno]

@Pretasoc, ha. I don't like this idea, but seriously, anyone putting XML comments on auto-properties ought to be hung, drawn and quartered (strictly figuratively) for cluttering code with pointless noise. 😆

[miloush]

@DavidArno can you explain why would auto-properties deserve any less documentation than fully implemented properties? You even get compiler warnings for not documenting public members.

[DavidArno]

Because I can tell what the following does in one line:

public bool Enabled {get; set}

And the additional information content of adding an XML comment, taking up four lines is precisely zero:

/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled {get; set}

The information content is still the same, but there's now three lines of non-information (ie noise) to wade through, which makes the file harder to read. It offers nothing useful intellisense-wise either.

Even worse, did you notice the error in the comment? It says "Gets". Yet the property supports set too. And comments disagreeing with the code are a very common thing. Now that noise also introduces uncertainty, ie we've just ramped up the entropy of the code. Pity the poor developer wading through that, versus just having that original, clear, one line to read. So just don't add them.

[canton7]

I don't want to derail this issue, but I think a lot of people would rather have too much documentation than too little, especially for public libraries. The number of nuget packages I've used which had a completely insufficient level of documentation on depresses me.

If I'm using a library and some property has noddy documentation on it, that at least tells me that there's no hidden complexity there. If a property is undocumented, I simply don't know whether that's because it was too simple to document, or whether it's actually got some weird side-effects or gotchas which the author just didn't bother to document.

Your circumstances and the users of your code will all affect your attitude to documentation, but let's not dismiss people who like seeing documentation.

[YairHalberstadt]

I think records may help provide an easy way to reduce clutter in data classes.

[Joe4evr]

This has been proposed before: #818.

[miloush]

I am sorry @DavidArno, but I cannot support your argument.

• You didn't actually answer how being an auto-property makes it any different from fully implemented property.
• You can see the code, but the documentation is for callers. Gets or sets is a valuable information in the property description and a also differentiator from fields.
• You are arguing that because people can do bad things, it is better to not allow anybody to do anything.
• Good for you having simple and understandable properties, but that's not always the case. Some even need the <returns> and <remarks> section. Again it is not about the code but about the usage.
• Imagine this is implemented and refactoring gets introduced to join several properties into this form of declaration, then "not putting XML comments" is not really an option, unless you think they should be all removed as a part of the refactoring.
• As I said you get compiler warnings out of the box when generating XML files and if your environment is set up to treat warnings as errors - not very fair suggesting developers in that situation should be all that figurative stuff :)

I randomly browsed Roslyn repository and found e.g. this property:
https://github.com/dotnet/roslyn/blob/master/src/Compilers/Core/MSBuildTask/Csc.cs#L109
There is no logic in the property and the name cannot be any better, yet still I find the XML documentation helpful... you don't?

[theunrepentantgeek]

public bool A, B, C { get; set; }

My first reaction on reading this is that you're declaring two public fields (A & B) and one public property (C). The opportunity for confusion is high enough that I expect folks would put this in the same category as combining multiple variable declarations into a single statement - possible, but unwise.

[theunrepentantgeek]

@DavidArno, I agree with you that this kind of documentation comment is worse than useless

/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled {get; set}

But I differ in the solution - I'd want the comment expanded to tell me more.

Assume we're talking about a WidgetProcessor ... what's the effect of setting Enabled to false? Does it mean that any existing widgets being processed are abandoned, or does their processing continue until complete? If it continues, how do I tell when it's done? If they're abandoned, are they dropped on the floor and lost forever, or are references retained so they can be processed later? If they're retained, when I set Enabled to true, does processing resume where it left off, or does it start from scratch? #somanyquestions

[CyrusNajmabadi]

Agreed. There are very simple settable boolean properties that may have deep implications for my type/system. Doc comments are vital here.

[DavidArno]

@miloush,

There is no logic in the property and the name cannot be any better, yet still I find the XML documentation helpful... you don't?

1. It's not an auto property.
2. It's not just inanely repeating the code, it contains extra info.
3. It's the only one of twenty properties in that file that has a comment. There's always exceptions to any rule, as that file demonstrates. It needs special explanation; the others don't.

[MV10]

Since the topic of docs has come up, I've been wondering, is XML commenting considered part of the C# language, or is it some corefx thing or even Rosyln? Where would a proposal go?

99% of the code I see only uses <summary> comments, without even internal markup like <para> so I've often wished for a way to eliminate the XML noise -- just /// and the summary text, with the assumption that it gets wrapped in <summary> behind the scenes . But each time I consider opening a proposal issue, it's then I realize I'm not sure if it's csharplang or not.

It would even cross-over into VS tooling, I guess, because I'd also like an editor option to control the default when I type ///...

[YairHalberstadt]

@MV10

Something like https://gist.github.com/sharwell/ab7a6ccab745c7e0a5b8662104e79735?

[HaloFour]

@MV10

I think that's proposed here: #2549

[MV10]

@HaloFour Thanks ... er, I even thumbed-up that one at some point in the past! 😀