4

I like to keep the comments and Xml documentation of my C# code fairly minimal. Preferring to make the code self-documenting where possible instead.

But the C# compiler gives a warning if I don't put an Xml comment on a destructor of a public class. Why is this?

Is there some useful information I should be putting into Xml comments here, which I've not been doing. I've never found the need to read the comments on a destructor myself. Is the compiler just being over-zealous?

Mark Cidade
  • 98,437
  • 31
  • 224
  • 236
Andy Lowry
  • 1,767
  • 13
  • 12
  • 4
    @Reed: By the way, it's a "destructor" in C#, not a finalizer. See section 10.13 of the specification, which begins "*A destructor is a member that implements the actions required to destruct an instance of a class.*" Many people believe this to have been a bad choice of name, and I agree. "Finalizer" would have been better. But they are called destructors, in C#, not finalizers. – Eric Lippert Mar 31 '11 at 16:03
  • 1
    @Reed Microsoft disagree I think: http://msdn.microsoft.com/en-us/library/66x5fx1b.aspx – Andy Lowry Mar 31 '11 at 16:03
  • 4
    @Reed: It depends which version of the spec you read. The ECMA spec refers to finalizers, but the MS spec still refers to destructors. – Jon Skeet Mar 31 '11 at 16:04
  • 1
    I suspect your point is that because no client can ever call the d'tor directly it seems unneccessary to write doc comments? – Steve Mar 31 '11 at 16:21
  • 1
    @Eric: Thanks - I'm used to looking at the ECMA spec. As Jon mentioned, it states it differently. – Reed Copsey Mar 31 '11 at 16:23
  • @Steve: Yes, and I don't think I've ever had a destructor without a Dispose, in which case all the interesting code would be in the Dispose. I can understand why Dispose would be documented. – Andy Lowry Mar 31 '11 at 16:27
  • The only time you ever want a destructor in C# is when you have an entirely new kind of unmanaged resource. For example, data access classes that hide away SqlConnections should _not_ need destructors. They only need IDisposable. Destruction is covered by the original SqlConnection. However, if you're building a whole new ADO.Net provider for a new kind of database that doesn't rely on existing providers, then you do need a destructor. – Joel Coehoorn Mar 31 '11 at 16:55

4 Answers4

2

If you turn on XML Doc comments, the compiler will want you to document everything in your API. The destructor is part of the API, and really should be included.

A destructor should typically only exist on IDisposable classes, and having it documented does help signal/remind people to call Dispose() on the object, as doing so (if implemented correctly) will significantly reduce GC pressure.

Reed Copsey
  • 554,122
  • 78
  • 1,158
  • 1,373
1

I suspect, although I have no proof, that the warning fires simply because it looks for doc comments on all methods that are not marked as private. I doubt there is a specific rule that destructors specifically need comments.

Steve
  • 8,469
  • 1
  • 26
  • 37
0

It might be helpful to anyone who uses your code to know exactly what it is that the finalizer does. In other words if you are working with a slew of unmanaged resources it would be helpful if the documentation clearly outlined what your class does with those resources when they are freed.

Andrew Hare
  • 344,730
  • 71
  • 640
  • 635
0

It insists on that because your class is public and the C# destructor ends up overriding a protected method, which is visible from outside your assembly.

Jordão
  • 55,340
  • 13
  • 112
  • 144
  • No, in C# the visibility of Finalize() is even less than private. Same for the destructor, you cannot call/see it even from inside the class. – H H Mar 31 '11 at 16:13
  • 1
    Your assembly might be reused by other languages than C#. – Jordão Mar 31 '11 at 16:15