Modify rule S115: Extend LaYC content (#3199)

rules/S115/common/how-to-fix-it.adoc

@@ -0,0 +1,6 @@
+First, familiarize yourself with the particular naming convention of the project
+in question.
+Then, update the name of the constant to match the convention, as well as all
+usages of the name.
+For many IDEs, you can use built-in renaming and refactoring features to update
+all usages of a constant at once.

rules/S115/common/introduction.adoc

@@ -0,0 +1,4 @@
+Constants should be named consistently to communicate intent and improve
+maintainability.
+Rename your constants to follow your project's naming convention to address this
+issue.

rules/S115/common/rule-behaviour.adoc

@@ -0,0 +1 @@
+This rule checks that all constant names match a given regular expression.

rules/S115/common/what-is-the-potential-impact.adoc

@@ -0,0 +1,4 @@
+Ignoring the naming convention for constants makes the code less readable since
+constants and variables are harder to tell apart.
+Code that is hard to understand is also difficult to maintain between different
+team members.

rules/S115/common/why-is-this-an-issue-thread-safety.adoc

@@ -0,0 +1,2 @@
+Or, in the case of primitive constants, that accessing the constant is
+thread-safe.

rules/S115/common/why-is-this-an-issue.adoc

@@ -0,0 +1,9 @@
+Constants are variables whose value does not change during the runtime of a
+program after initialization.
+Oftentimes, constants are used in multiple locations across different
+subroutines.
+
+It is important that the names of constants follow a consistent and easily
+recognizable pattern.
+This way, readers immediately understand that the referenced value does not
+change, which simplifies debugging.

rules/S115/flex/rule.adoc

@@ -1,19 +1,34 @@
+include::../common/introduction.adoc[]
+
 == Why is this an issue?
 
-include::../description.adoc[]
+include::../common/why-is-this-an-issue.adoc[]
+
+include::../common/rule-behaviour.adoc[]
+
+=== What is the potential impact?
+
+include::../common/what-is-the-potential-impact.adoc[]
+
+== How to fix it
+
+include::../common/how-to-fix-it.adoc[]
+
+=== Code examples
 
-=== Noncompliant code example
+==== Noncompliant code example
 
-With the default regular expression ``++^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$++``:
+The following example assumes that constant names should match the default
+regular expression ``++^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$++``:
 
-[source,flex]
+[source,flex,diff-id=1,diff-type=noncompliant]
 ----
 public static const first:String = "first";
 ----
 
-=== Compliant solution
+==== Compliant solution
 
-[source,flex]
+[source,flex,diff-id=1,diff-type=compliant]
 ----
 public static const FIRST:String = "first";
 ----
@@ -24,14 +39,14 @@ ifdef::env-github,rspecator-view[]
 == Implementation Specification
 (visible only on this page)
 
-include::../message.adoc[]
+include::../common/message.adoc[]
 
-include::../parameters.adoc[]
+include::../common/parameters.adoc[]
 
 '''
 == Comments And Links
 (visible only on this page)
 
-include::../comments-and-links.adoc[]
+include::../common/comments-and-links.adoc[]
 
 endif::env-github,rspecator-view[]

rules/S115/java/rule.adoc

@@ -1,49 +1,82 @@
+include::../common/introduction.adoc[]
+
 == Why is this an issue?
 
-include::../description.adoc[]
+include::../common/why-is-this-an-issue.adoc[]
+
+include::../common/why-is-this-an-issue-thread-safety.adoc[]
+
+include::../common/rule-behaviour.adoc[]
+
+=== What is the potential impact?
+
+include::../common/what-is-the-potential-impact.adoc[]
+
+== How to fix it
+
+include::../common/how-to-fix-it.adoc[]
 
-=== Noncompliant code example
+=== Code examples
 
-With the default regular expression ``++^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$++``:
+==== Noncompliant code example
 
-[source,java]
+The following example assumes that constant names should match the default
+regular expression ``++^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$++``:
+
+[source,java,diff-id=1,diff-type=noncompliant]
 ----
 public class MyClass {
-  public static final int first = 1;
+  public static final float pi = 3.14159f; // Noncompliant: Constant is not capitalized
+
+  void myMethod() {
+    System.out.println(pi);
+  }
 }
 
 public enum MyEnum {
-  first;
+  optionOne, // Noncompliant
+  optionTwo; // Noncompliant
 }
 ----
 
-=== Compliant solution
+==== Compliant solution
 
-[source,java]
+[source,java,diff-id=1,diff-type=compliant]
 ----
 public class MyClass {
-  public static final int FIRST = 1; 
+  public static final float PI = 3.14159f;
+
+  void myMethod() {
+    System.out.println(PI);
+  }
 }
 
 public enum MyEnum {
-  FIRST;
+  OPTION_ONE,
+  OPTION_TWO;
 }
 ----
 
+== Resources
+
+=== External coding guidelines
+
+* https://google.github.io/styleguide/javaguide.html#s5.2.4-constant-names[The Google Java Style Guide on Constant Names].
+
 ifdef::env-github,rspecator-view[]
 
 '''
 == Implementation Specification
 (visible only on this page)
 
-include::../message.adoc[]
+include::../common/message.adoc[]
 
-include::../parameters.adoc[]
+include::../common/parameters.adoc[]
 
 '''
 == Comments And Links
 (visible only on this page)
 
-include::../comments-and-links.adoc[]
+include::../common/comments-and-links.adoc[]
 
 endif::env-github,rspecator-view[]

rules/S115/php/rule.adoc

@@ -1,12 +1,27 @@
+include::../common/introduction.adoc[]
+
 == Why is this an issue?
 
-include::../description.adoc[]
+include::../common/why-is-this-an-issue.adoc[]
+
+include::../common/rule-behaviour.adoc[]
+
+=== What is the potential impact?
+
+include::../common/what-is-the-potential-impact.adoc[]
+
+== How to fix it
 
-=== Noncompliant code example
+include::../common/how-to-fix-it.adoc[]
 
-With the default regular expression ``++^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$++``:
+=== Code examples
 
-[source,php]
+==== Noncompliant code example
+
+The following example assumes that constant names should match the default
+regular expression ``++^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$++``:
+
+[source,php,diff-id=1,diff-type=noncompliant]
 ----
 define("const1", true);
 
@@ -15,9 +30,9 @@ class Foo {
 }
 ----
 
-=== Compliant solution
+==== Compliant solution
 
-[source,php]
+[source,php,diff-id=1,diff-type=compliant]
 ----
 define("CONST1", true);
 
@@ -26,20 +41,26 @@ class Foo {
 }
 ----
 
+== Resources
+
+=== External coding guidelines
+
+* https://www.php-fig.org/psr/psr-1/[The PSR-1: Basic Coding Standard]
+
 ifdef::env-github,rspecator-view[]
 
 '''
 == Implementation Specification
 (visible only on this page)
 
-include::../message.adoc[]
+include::../common/message.adoc[]
 
-include::../parameters.adoc[]
+include::../common/parameters.adoc[]
 
 '''
 == Comments And Links
 (visible only on this page)
 
-include::../comments-and-links.adoc[]
+include::../common/comments-and-links.adoc[]
 
 endif::env-github,rspecator-view[]

rules/S115/plsql/rule.adoc

@@ -1,12 +1,27 @@
+include::../common/introduction.adoc[]
+
 == Why is this an issue?
 
-include::../description.adoc[]
+include::../common/why-is-this-an-issue.adoc[]
+
+include::../common/rule-behaviour.adoc[]
+
+=== What is the potential impact?
+
+include::../common/what-is-the-potential-impact.adoc[]
+
+== How to fix it
+
+include::../common/how-to-fix-it.adoc[]
+
+=== Code examples
 
-=== Noncompliant code example
+==== Noncompliant code example
 
-With the default regular expression ``++[a-zA-Z]([a-zA-Z0-9_]*[a-zA-Z0-9])?++``:
+The following example assumes that constant names should match the default
+regular expression ``++[a-zA-Z]([a-zA-Z0-9_]*[a-zA-Z0-9])?++``:
 
-[source,sql]
+[source,sql,diff-id=1,diff-type=noncompliant]
 ----
 DECLARE
   constant_ CONSTANT PLS_INTEGER := 42; -- Noncompliant
@@ -16,9 +31,9 @@ END;
 /
 ----
 
-=== Compliant solution
+==== Compliant solution
 
-[source,sql]
+[source,sql,diff-id=1,diff-type=compliant]
 ----
 DECLARE
   constant CONSTANT PLS_INTEGER := 42; -- Compliant
@@ -34,7 +49,7 @@ ifdef::env-github,rspecator-view[]
 == Implementation Specification
 (visible only on this page)
 
-include::../message.adoc[]
+include::../common/message.adoc[]
 
 === Parameters
 
@@ -53,6 +68,6 @@ The regular expression the name should match.
 == Comments And Links
 (visible only on this page)
 
-include::../comments-and-links.adoc[]
+include::../common/comments-and-links.adoc[]
 
 endif::env-github,rspecator-view[]

rules/S115/swift/rule.adoc

@@ -1,30 +1,53 @@
+include::../common/introduction.adoc[]
+
 == Why is this an issue?
 
-include::../description.adoc[]
+include::../common/why-is-this-an-issue.adoc[]
+
+include::../common/why-is-this-an-issue-thread-safety.adoc[]
+
+include::../common/rule-behaviour.adoc[]
+
+=== What is the potential impact?
+
+include::../common/what-is-the-potential-impact.adoc[]
+
+== How to fix it
 
-=== Noncompliant code example
+include::../common/how-to-fix-it.adoc[]
 
-With the default regular expression ``++^[a-z][a-zA-Z0-9]*$++``:
+=== Code examples
 
-[source,swift]
+==== Noncompliant code example
+
+The following example assumes that constant names should match the default
+regular expression ``++^[a-z][a-zA-Z0-9]*$++``:
+
+[source,swift,diff-id=1,diff-type=noncompliant]
 ----
 let Pi = 3.14
 ----
 
-=== Compliant solution
+==== Compliant solution
 
-[source,swift]
+[source,swift,diff-id=1,diff-type=compliant]
 ----
 let pi = 3.14
 ----
 
+== Resources
+
+=== External coding guidelines
+
+* https://www.swift.org/documentation/api-design-guidelines/#conventions[Case Conventions] in the Swift API Design Guidelines
+
 ifdef::env-github,rspecator-view[]
 
 '''
 == Implementation Specification
 (visible only on this page)
 
-include::../message.adoc[]
+include::../common/message.adoc[]
 
 === Parameters
 
@@ -49,6 +72,6 @@ Regular expression used to check the constant names against.
 === on 15 May 2015, 11:56:52 Ann Campbell wrote:
 None whatsoever [~elena.vilchik]. You're the language expert! :-)
 
-include::../comments-and-links.adoc[]
+include::../common/comments-and-links.adoc[]
 
 endif::env-github,rspecator-view[]