diff --git a/rules/S117/azureresourcemanager/metadata.json b/rules/S117/azureresourcemanager/metadata.json new file mode 100644 index 00000000000..85af50f966f --- /dev/null +++ b/rules/S117/azureresourcemanager/metadata.json @@ -0,0 +1,3 @@ +{ + "title": "Parameter and variable names should comply with a naming convention" +} diff --git a/rules/S117/azureresourcemanager/rule.adoc b/rules/S117/azureresourcemanager/rule.adoc new file mode 100644 index 00000000000..e3cff6d098e --- /dev/null +++ b/rules/S117/azureresourcemanager/rule.adoc @@ -0,0 +1,104 @@ +:identifier_capital_plural: Parameters and variables +:identifier: parameter and variable +:identifier_plural: parameters and variables +:identifier_or: parameter or variable +:regex: ^[a-z][a-zA-Z0-9]*$ + +include::../introduction.adoc[] + +include::../why-is-this-an-issue.adoc[] + +include::../what-is-the-potential-impact.adoc[] + +== How to fix it in ARM templates + +include::../how-to-fix-it-description.adoc[] + +=== Code examples + +==== Noncompliant code example + +[source,json,diff-id=1,diff-type=noncompliant] +---- +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "parameters": { + "storage_account_name": { + "type": "string" + } + }, + "variables": { + "string_variable": "example value" + } +} +---- + +==== Compliant solution + +[source,json,diff-id=1,diff-type=compliant] +---- +{ + "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", + "contentVersion": "1.0.0.0", + "parameters": { + "storageAccountName": { + "type": "string" + } + }, + "variables": { + "stringVariable": "example value" + } +} +---- + +== How to fix it in Bicep + +include::../how-to-fix-it-description.adoc[] + +=== Code examples + +==== Noncompliant code example + +[source,bicep,diff-id=2,diff-type=noncompliant] +---- +param storage_account_name string // Noncompliant +var string_variable = 'example val' // Noncompliant +---- + +==== Compliant solution + +[source,bicep,diff-id=2,diff-type=compliant] +---- +param storageAccountName string +var stringVariable = 'example val' +---- + +== Resources + +=== Documentation + +* Microsoft - https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/best-practices#parameters[ARM template best practices] +* Microsoft - https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/best-practices#names[Best practices for Bicep] +* Microsoft - https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/variables[Variables in ARM templates] +* Microsoft - https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/parameters[Parameters in ARM templates] +* Microsoft - https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/variables[Variables in Bicep] +* Microsoft - https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/parameters[Parameters in Bicep] + +ifdef::env-github,rspecator-view[] + +''' +== Implementation Specification +(visible only on this page) + +include::../message.adoc[] + +include::../parameters.adoc[] + +''' +== Comments And Links +(visible only on this page) + +include::../comments-and-links.adoc[] + +endif::env-github,rspecator-view[] diff --git a/rules/S117/how-to-fix-it-description.adoc b/rules/S117/how-to-fix-it-description.adoc new file mode 100644 index 00000000000..98194a3cca2 --- /dev/null +++ b/rules/S117/how-to-fix-it-description.adoc @@ -0,0 +1,6 @@ +First, familiarize yourself with the particular naming convention of the project +in question. +Then, update the name 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 at once. diff --git a/rules/S117/how-to-fix-it.adoc b/rules/S117/how-to-fix-it.adoc index 8f1f4d34fd8..2d9f1db0065 100644 --- a/rules/S117/how-to-fix-it.adoc +++ b/rules/S117/how-to-fix-it.adoc @@ -1,8 +1,3 @@ == How to fix it -First, familiarize yourself with the particular naming convention of the project -in question. -Then, update the name 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 at once. +include::how-to-fix-it-description.adoc[] diff --git a/rules/S117/what-is-the-potential-impact.adoc b/rules/S117/what-is-the-potential-impact.adoc index 9f91d1a08b5..cf3c5c38139 100644 --- a/rules/S117/what-is-the-potential-impact.adoc +++ b/rules/S117/what-is-the-potential-impact.adoc @@ -2,14 +2,14 @@ Inconsistent naming of {identifier_plural} can lead to several issues in your code: -* Reduced Readability: inconsistent {identifier} names make the code harder to read and understand; consequently, it is more difficult to identify the purpose of each variable, spot errors, or comprehend the logic. +* *Reduced Readability*: Inconsistent {identifier} names make the code harder to read and understand; consequently, it is more difficult to identify the purpose of each variable, spot errors, or comprehend the logic. -* Difficulty in Identifying Variables: {identifier_plural} that don't adhere to a standard naming convention are challenging to identify; thus, the coding process slows down, especially when dealing with a large codebase. +* *Difficulty in Identifying Variables*: The {identifier_plural} that don't adhere to a standard naming convention are challenging to identify; thus, the coding process slows down, especially when dealing with a large codebase. -* Increased Risk of Errors: inconsistent or unclear {identifier} names lead to misunderstandings about what the variable represents. This ambiguity leads to incorrect assumptions and, consequently, bugs in the code. +* *Increased Risk of Errors*: Inconsistent or unclear {identifier} names lead to misunderstandings about what the variable represents. This ambiguity leads to incorrect assumptions and, consequently, bugs in the code. -* Collaboration Difficulties: in a team setting, inconsistent naming conventions lead to confusion and miscommunication among team members. +* *Collaboration Difficulties*: In a team setting, inconsistent naming conventions lead to confusion and miscommunication among team members. -* Difficulty in Code Maintenance: inconsistent naming leads to an inconsistent codebase. The code is difficult to understand, and making changes feels like refactoring constantly, as you face different naming methods. Ultimately, it makes the codebase harder to maintain. +* *Difficulty in Code Maintenance*: Inconsistent naming leads to an inconsistent codebase. The code is difficult to understand, and making changes feels like refactoring constantly, as you face different naming methods. Ultimately, it makes the codebase harder to maintain. In summary, not adhering to a naming convention for {identifier_plural} can lead to confusion, errors, and inefficiencies, making the code harder to read, understand, and maintain.