rspec/rules/S2953/csharp/rule.adoc

== Why is this an issue?

https://learn.microsoft.com/en-us/dotnet/api/system.idisposable[IDisposable] is an interface implemented by all types which need to provide a mechanism for https://learn.microsoft.com/en-us/dotnet/standard/garbage-collection/unmanaged[releasing unmanaged resources].

Unlike managed memory, which is taken care of by the https://learn.microsoft.com/en-us/dotnet/standard/garbage-collection/fundamentals[garbage collection], 

The interface declares a https://learn.microsoft.com/en-us/dotnet/api/system.idisposable.dispose[Dispose] method, which the implementer has to define.

The method name `Dispose` should be used exclusively to implement `IDisposable.Dispose` to prevent any confusion.

It may be tempting to create a `Dispose` method for other purposes, but doing so will result in confusion and likely lead to problems in production.

=== Exceptions

Methods named `Dispose` and invoked from the `IDisposable.Dispose` implementation are not reported.

[source,csharp]
----
public class GarbageDisposal : IDisposable
{
  protected virtual void Dispose(bool disposing)
  {
    //...
  }
  public void Dispose() 
  {
    Dispose(true);
    GC.SuppressFinalize(this);
  }
}
----

== How to fix it

First, it is important to determine whether instances of the type defining the `Dispose` method should support the https://learn.microsoft.com/en-us/dotnet/api/system.idisposable[IDisposable] interface or not.

The decision would be based on whether the instance can have unmanaged resources which have to be dealt with, upon destruction or earlier in the lifetime of the object.

The https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/dispose-pattern[Dispose pattern] can help to take the decision.

If the type should not support the pattern, the `Dispose` method should be renamed to something which is different than `Dispose`, but still relevant and possibly more specific to the context. 

=== Code examples

==== Noncompliant code example

[source,csharp]
----
public class GarbageDisposal 
{
  private int Dispose()  // Noncompliant
  {
    // ...
  }
}
----

==== Compliant solution

[source,csharp]
----
public class GarbageDisposal : IDisposable
{
  public void Dispose() 
  {
    // ...
  }
}
----
or

[source,csharp]
----
public class GarbageDisposal 
{
  private int Grind()
  {
    // ...
  }
}
----

== Resources

=== Documentation

* https://learn.microsoft.com/en-us/dotnet/standard/garbage-collection/fundamentals[Fundamentals of garbage collection]
* https://learn.microsoft.com/en-us/dotnet/standard/garbage-collection/unmanaged[Cleaning up unmanaged resources]
* https://learn.microsoft.com/en-us/dotnet/api/system.idisposable[IDisposable Interface]
* https://learn.microsoft.com/en-us/dotnet/standard/garbage-collection/implementing-dispose[Implement a Dispose method]


ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Either implement "IDisposable.Dispose", or rename this method to prevent confusion.


'''
== Comments And Links
(visible only on this page)

=== relates to: S1201

=== on 22 May 2015, 09:54:56 Tamas Vajk wrote:
LGTM

=== on 9 Jun 2015, 09:05:39 Tamas Vajk wrote:
\[~ann.campbell.2] I've changed all occurrences of "override" to "implement". I think it is better this way.

=== on 9 Jun 2015, 13:46:11 Ann Campbell wrote:
okay, thanks [~tamas.vajk]

=== on 18 Jun 2015, 11:41:33 Tamas Vajk wrote:
\[~ann.campbell.2] I've added an exception. This is a usual pattern in C#. You can read about it here: \https://msdn.microsoft.com/en-us/library/b1yfkh5e(v=vs.110).aspx

=== on 18 Jun 2015, 12:00:49 Ann Campbell wrote:
okay [~tamas.vajk]

=== on 4 Aug 2015, 18:14:10 Ann Campbell wrote:
\[~tamas.vajk] I've just mapped this to FxCop's ImplementIDisposableCorrectly, but I believe that rule is broader than this one.

=== on 5 Aug 2015, 13:23:50 Tamas Vajk wrote:
\[~ann.campbell.2] Yes, it seems to me too that it is doing more. I'm not sure if we would want to add more disposable rules, or cover all the cases of this FxCop rule in this RSPEC.

=== on 20 Nov 2019, 10:31:27 Costin Zaharia wrote:
We should add an exception in this rule for https://docs.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-8#disposable-ref-structs[disposable ref structs] introduced in C# 8.

endif::env-github,rspecator-view[]