Modify rule S1186: LaYC format (#2095)

rules/S1186/csharp/comment-code.adoc

@@ -0,0 +1,9 @@
+In this case, it is important to put a comment explaining the reason for the empty implementation.
+
+[source,csharp]
+----
+void DoSomething() // Compliant
+{
+    // Do nothing because of X
+}
+----

rules/S1186/csharp/empty-code.adoc

@@ -0,0 +1,4 @@
+[source,csharp]
+----
+void DoSomething() { } // Noncompliant
+----

rules/S1186/csharp/notimplemented-code.adoc

@@ -0,0 +1,7 @@
+You can make clear the initial intention to add an implementation in the future by throwing the https://learn.microsoft.com/en-us/dotnet/api/system.notsupportedexception[`NotSupportedException`].
+
+[source,csharp]
+----
+void DoSomething() => // Compliant
+    throw new NotImplementedException();
+----

rules/S1186/csharp/notsupported-code.adoc

@@ -0,0 +1,7 @@
+You can make clear the initial intention not to implement the method in the future by throwing the https://learn.microsoft.com/en-us/dotnet/api/system.notsupportedexception[`NotSupportedException`].
+
+[source,csharp]
+----
+void DoSomething() => // Compliant
+    throw new NotSupportedException();
+----

rules/S1186/csharp/rule.adoc

@@ -1,47 +1,20 @@
 == Why is this an issue?
 
-There are several reasons for a method not to have a method body:
+:operationName: method
+:emptyCode: csharp/empty-code.adoc
+:notsupportedCode: csharp/notsupported-code.adoc
+:notimplementedCode: csharp/notimplemented-code.adoc
+:commentCode: csharp/comment-code.adoc
 
-
-* It is an unintentional omission, and should be fixed.
-* It is not yet, or never will be, supported. In this case a ``++NotSupportedException++`` should be thrown.
-* The method is an intentionally-blank override. In this case a nested comment should explain the reason for the blank override.
-
-=== Noncompliant code example
-
-[source,csharp]
-----
-public override void DoSomething() 
-{
-}
-
-public override void DoSomethingElse() 
-{
-}
-----
-
-=== Compliant solution
-
-[source,csharp]
-----
-public override void DoSomething() 
-{
-  // Do nothing because of X and Y.
-}
-
-public override void DoSomethingElse() 
-{
-  throw new NotSupportedException();
-}
-----
+include::../why-dotnet.adoc[]
 
 === Exceptions
 
-The following methods are ignored:
+The following empty methods are considered compliant:
 
-* empty ``++virtual++`` methods,
-* empty methods that override an ``++abstract++`` method,
-* empty overrides in test assemblies.
+* empty `virtual` methods as the implementation might not be required in the base class
+* empty methods that override an `abstract` method as the implementation is mandatory for child class
+* empty overrides in test assemblies for mocking purposes
 
 ifdef::env-github,rspecator-view[]
 
@@ -58,9 +31,6 @@ include::../message.adoc[]
 === on 11 Nov 2020, 19:45:36 Andrei Epure wrote:
 \[~nicolas.harraudeau] I believe this rule could also apply to local functions and to property setters, right?
 
-
- 
-
 ----
 public void Method()
 {

rules/S1186/vb6/comment-code.adoc

@@ -0,0 +1,8 @@
+In this case, it is important to put a comment explaining the reason for the empty implementation.
+
+[source,vb6,diff-id=1,diff-type=compliant]
+----
+Sub DoSomething()
+    ' Do nothing because of X
+End Sub
+----

rules/S1186/vb6/empty-code.adoc

@@ -0,0 +1,5 @@
+[source,vb6,diff-id=1,diff-type=noncompliant]
+----
+Sub DoSomething()
+End Sub
+----

rules/S1186/vb6/notimplemented-code.adoc

@@ -0,0 +1,8 @@
+In order to provide the initial intention to add an implementation in the future, you can raise an error and specify that the procedure is not implemented yet.
+
+[source,vb6,diff-id=1,diff-type=compliant]
+----
+Sub DoSomething()
+    Err.Raise(1, , "NotImplemented")
+End Sub
+----

rules/S1186/vb6/notsupported-code.adoc

@@ -0,0 +1,8 @@
+In order to provide the initial intention to not add an implementation in the future, you can raise an error and specify that the procedure will not be implemented.
+
+[source,vb6,diff-id=1,diff-type=compliant]
+----
+Sub DoSomething()
+    Err.Raise(1, , "NotSupported")
+End Sub
+----

rules/S1186/vb6/rule.adoc

@@ -1,35 +1,12 @@
 == Why is this an issue?
 
-There are several reasons for a method not to have a method body:
+:operationName: procedure
+:emptyCode: vb6/empty-code.adoc
+:notsupportedCode: vb6/notsupported-code.adoc
+:notimplementedCode: vb6/notimplemented-code.adoc
+:commentCode: vb6/comment-code.adoc
 
-
-* It is an unintentional omission, and should be fixed.
-* It is not yet, or never will be, supported. In this case an error should be thrown.
-* The method is an intentionally-blank. In this case a nested comment should explain the reason for the blank method.
-
-=== Noncompliant code example
-
-[source,vb6]
-----
-Sub DoSomething()
-End Sub
-
-Function DoSomething() As String
-End Function
-----
-
-=== Compliant solution
-
-[source,vb6]
-----
-Sub DoSomething()
-    ' Not implemented because of reason
-End Sub
-
-Function DoSomething() As String
-    DoSomething = "Value"
-End Function
-----
+include::../why-dotnet.adoc[]
 
 ifdef::env-github,rspecator-view[]
 

rules/S1186/vbnet/comment-code.adoc

@@ -0,0 +1,8 @@
+In this case, it is important to put a comment explaining the reason for the empty implementation.
+
+[source,vbnet]
+----
+Sub DoSomething() ' Compliant
+    ' Do nothing because of X
+End Sub
+----

rules/S1186/vbnet/empty-code.adoc

@@ -0,0 +1,5 @@
+[source,vbnet]
+----
+Sub DoSomething() ' Noncompliant
+End Sub
+----

rules/S1186/vbnet/notimplemented-code.adoc

@@ -0,0 +1,8 @@
+By throwing the https://learn.microsoft.com/en-us/dotnet/api/system.notimplementedexception[`NotImplementedException`], the initial intention to add an implementation in the future is clear.
+
+[source,vbnet]
+----
+Sub DoSomething() ' Compliant
+    Throw New NotImplementedException
+End Sub
+----

rules/S1186/vbnet/notsupported-code.adoc

@@ -0,0 +1,8 @@
+By throwing the https://learn.microsoft.com/en-us/dotnet/api/system.notsupportedexception[`NotSupportedException`], it makes clear the initial intention not to implement it in the future.
+
+[source,vbnet]
+----
+Sub DoSomething() ' Compliant
+    Throw New NotSupportedException
+End Sub
+----

rules/S1186/vbnet/rule.adoc

@@ -1,43 +1,20 @@
 == Why is this an issue?
 
-There are several reasons for a method not to have a method body:
+:operationName: method
+:emptyCode: vbnet/empty-code.adoc
+:notsupportedCode: vbnet/notsupported-code.adoc
+:notimplementedCode: vbnet/notimplemented-code.adoc
+:commentCode: vbnet/comment-code.adoc
 
-
-* It is an unintentional omission, and should be fixed.
-* It is not yet, or never will be, supported. In this case a ``++NotSupportedException++`` should be thrown.
-* The method is an intentionally-blank override. In this case a nested comment should explain the reason for the blank override.
-
-=== Noncompliant code example
-
-[source,vbnet]
-----
-Sub DoSomething()
-End Sub
-
-Function DoSomething() As String
-End Function
-----
-
-=== Compliant solution
-
-[source,vbnet]
-----
-Sub DoSomething()
-    ' Not implemented because of reason
-End Sub
-
-Function DoSomething() As String
-    Throw New NotSupportedException
-End Function
-----
+include::../why-dotnet.adoc[]
 
 === Exceptions
 
-The following methods are ignored:
+The following empty methods are considered compliant:
 
-* empty ``++Overridable++`` or ``++MustOverride++`` methods,
-* empty methods that override an ``++MustOverride++`` method,
-* empty overrides in test assemblies.
+* empty `Overridable` methods, as the implementation might not be required in the base class
+* empty methods that override a `MustOverride` method as the implementation is mandatory for child class
+* empty overrides in test assemblies for mocking purposes
 
 ifdef::env-github,rspecator-view[]
 

rules/S1186/why-dotnet.adoc

@@ -0,0 +1,26 @@
+An empty {operationName} is generally considered bad practice and can lead to confusion, readability, and maintenance issues.
+Empty {operationName}s bring no functionality and are misleading to others as they might think the {operationName} implementation fulfills a specific and identified requirement.
+
+Such {operationName}s should be avoided and possibly removed.
+
+include::{emptyCode}[]
+
+However, there are some cases where a {operationName} needs to be empty. In those cases, it is essential to minimize confusion and enhance clarity.
+
+Here are a few examples:
+
+* The {operationName} will never be implemented.
++
+--
+include::{notsupportedCode}[]
+--
+* The {operationName} will be implemented in the future.
++
+--
+include::{notimplementedCode}[]
+--
+* The {operationName} implementation is empty intentionally.
++
+--
+include::{commentCode}[]
+--