Closing #141 - var guidance

.github/workflows/ConvertGuidelinesXmlToMarkdown.yml

@@ -41,7 +41,7 @@ jobs:
 
     - name: restore_compile_run_createMD
       run: >
-         dotnet run --configuration Release --project ./XMLtoMD/GuidelineXmlToMD/GuidelineXmlToMD.csproj 
+         dotnet run --configuration Release --project ./Tools/XMLtoMD/GuidelineXmlToMD/GuidelineXmlToMD.csproj 
          -- --xml-input-file "./docs/${{ env.XmlFileName }}" --markdown-output-file "./docs/coding/csharp.md"
       if: ${{ steps.diff.outputs.modified == 'true' }}
 

.github/workflows/manuallyRunXmlToMD.yml

@@ -31,7 +31,7 @@ jobs:
 
     - name: restore_compile_run_createMD
       run: >
-         dotnet run --configuration Release --project ./XMLtoMD/GuidelineXmlToMD/GuidelineXmlToMD.csproj 
+         dotnet run --configuration Release --project ./Tools/XMLtoMD/GuidelineXmlToMD/GuidelineXmlToMD.csproj 
          -- --xml-input-file "./docs/${{ env.XmlFileName }}" --markdown-output-file "./docs/coding/csharp.md"
 
     - name: Create commit and push to CodingGuideLinesMDUpdate

.gitignore

@@ -349,4 +349,5 @@ healthchecksdb
 MigrationBackup/
 
 .idea
-.DS_Store
+.DS_Store
+.devcontainer

Tools/XMLtoMD/GuidelineXmlToMD.Test/Data/TestGuidelines.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Guidelines>
+  <guideline key="name" severity="CONSIDER" section="Fencing" subsection="Who">My name is Inigo Montoya.</guideline>
+</Guidelines>

Tools/XMLtoMD/GuidelineXmlToMD.Test/GuidelineXmlFileReaderTest.cs

@@ -0,0 +1,29 @@
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+
+namespace GuidelineXmlToMD.Test
+{
+    [TestClass]
+    public class GuidelineXmlFileReaderTest
+    {
+        [TestMethod]
+        public void ReadExisitingGuidelinesFile_ExistingFile_ReadsGuidlines()
+        {
+            // Arrange
+            var projectPath = Directory.GetParent(Environment.CurrentDirectory).Parent.Parent.FullName;
+            var testPath = Path.Combine(projectPath, @"Data\", "TestGuidelines.xml");
+
+            // Act
+            ICollection<Guideline> guidelines = GuidelineXmlFileReader.ReadExisitingGuidelinesFile(testPath);
+
+            // Assert
+            var actual = guidelines.Single();
+            var expected = new Guideline("name", "My name is Inigo Montoya.", "CONSIDER", "Fencing", "Who");
+            Assert.AreEqual(expected, actual);
+
+        }
+    }
+}

Tools/XMLtoMD/GuidelineXmlToMD.Test/GuidelineXmlToMD.Test.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net5.0</TargetFramework>
+    <NoWarn>CA2007,CA1815,CA1303,CA1707,CA1305,IDE0008,INTL0003</NoWarn>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="16.7.1" />
+    <PackageReference Include="MSTest.TestAdapter" Version="2.1.1" />
+    <PackageReference Include="MSTest.TestFramework" Version="2.1.1" />
+    <PackageReference Include="coverlet.collector" Version="1.3.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\GuidelineXmlToMD\GuidelineXmlToMD.csproj" />
+  </ItemGroup>
+
+</Project>

XMLtoMD/GuidelineXmlToMD/GuidelineXmlToMD.sln → Tools/XMLtoMD/GuidelineXmlToMD.sln

@@ -3,16 +3,18 @@ Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 16
 VisualStudioVersion = 16.0.30225.117
 MinimumVisualStudioVersion = 10.0.40219.1
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "GuidelineXmlToMD", "GuidelineXmlToMD.csproj", "{D9C7CC15-01DB-46FE-922A-6EB41CE1759B}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "GuidelineXmlToMD", "GuidelineXmlToMD\GuidelineXmlToMD.csproj", "{D9C7CC15-01DB-46FE-922A-6EB41CE1759B}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{2D6BFDEE-B212-4BD3-A8D4-750F9BF9ACDE}"
 	ProjectSection(SolutionItems) = preProject
-		..\..\.github\workflows\ConvertGuidelinesXmlToMarkdown.yml = ..\..\.github\workflows\ConvertGuidelinesXmlToMarkdown.yml
-		..\..\docs\coding\csharp.md = ..\..\docs\coding\csharp.md
-		..\..\docs\Guidelines(8th Edition).xml = ..\..\docs\Guidelines(8th Edition).xml
-		..\..\.github\workflows\manuallyRunXmlToMD.yml = ..\..\.github\workflows\manuallyRunXmlToMD.yml
+		..\..\..\.github\workflows\ConvertGuidelinesXmlToMarkdown.yml = ..\..\..\.github\workflows\ConvertGuidelinesXmlToMarkdown.yml
+		..\..\..\docs\coding\csharp.md = ..\..\..\docs\coding\csharp.md
+		..\..\..\docs\Guidelines(8th Edition).xml = ..\..\..\docs\Guidelines(8th Edition).xml
+		..\..\..\.github\workflows\manuallyRunXmlToMD.yml = ..\..\..\.github\workflows\manuallyRunXmlToMD.yml
 	EndProjectSection
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GuidelineXmlToMD.Test", "GuidelineXmlToMD.Test\GuidelineXmlToMD.Test.csproj", "{53970A22-98C6-4383-B4D4-03C698176FC5}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -23,6 +25,10 @@ Global
 		{D9C7CC15-01DB-46FE-922A-6EB41CE1759B}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{D9C7CC15-01DB-46FE-922A-6EB41CE1759B}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{D9C7CC15-01DB-46FE-922A-6EB41CE1759B}.Release|Any CPU.Build.0 = Release|Any CPU
+		{53970A22-98C6-4383-B4D4-03C698176FC5}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{53970A22-98C6-4383-B4D4-03C698176FC5}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{53970A22-98C6-4383-B4D4-03C698176FC5}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{53970A22-98C6-4383-B4D4-03C698176FC5}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

Tools/XMLtoMD/GuidelineXmlToMD/Guideline.cs

@@ -0,0 +1,4 @@
+namespace GuidelineXmlToMD
+{
+    public record Guideline(string Key, string Text, string Severity, string Section, string Subsection) { };
+}

Tools/XMLtoMD/GuidelineXmlToMD/GuidelineXmlFileReader.cs

@@ -0,0 +1,37 @@
+using System.Collections.Generic;
+using System.Linq;
+using System.Xml.Linq;
+
+namespace GuidelineXmlToMD
+{
+    public static class GuidelineXmlFileReader
+    {
+        private const string _Key = "key";
+        private const string _Severity = "severity";
+        private const string _Section = "section";
+        private const string _Subsection = "subsection";
+
+
+        public static ICollection<Guideline> ReadExisitingGuidelinesFile(string pathToExistingGuidelinesXml)
+        {
+
+            XDocument previousGuidelines = XDocument.Load(pathToExistingGuidelinesXml);
+
+            HashSet<Guideline> guidelines = new HashSet<Guideline>();
+
+            foreach (XElement guidelineFromXml in previousGuidelines.Root.DescendantNodes().OfType<XElement>())
+            {
+                Guideline guideline = new Guideline(
+                    Key: guidelineFromXml.Attribute(_Key)?.Value,
+                    Text: guidelineFromXml?.Value,
+                    Severity: guidelineFromXml.Attribute(_Severity)?.Value,
+                    Section: guidelineFromXml.Attribute(_Section)?.Value,
+                    Subsection: guidelineFromXml.Attribute(_Subsection)?.Value
+                );
+                guidelines.Add(guideline);
+            }
+            return guidelines;
+        }
+
+    }
+}

XMLtoMD/GuidelineXmlToMD/Properties/launchSettings.json → Tools/XMLtoMD/GuidelineXmlToMD/Properties/launchSettings.json

@@ -2,7 +2,7 @@
   "profiles": {
     "GuidelineXmlToMD": {
       "commandName": "Project",
-      "commandLineArgs": "--xml-input-file \"..\\..\\..\\..\\..\\docs\\Guidelines(8th Edition).xml\" --markdown-output-file \"..\\..\\..\\..\\..\\docs\\coding\\csharp.md\""
+      "commandLineArgs": "--xml-input-file \"..\\..\\..\\..\\..\\..\\docs\\Guidelines(8th Edition).xml\" --markdown-output-file \"..\\..\\..\\..\\..\\..\\docs\\coding\\csharp.md\""
     }
   }
 }

docs/Guidelines(8th Edition).xml

@@ -99,7 +99,7 @@
   <guideline key="Ch06_d75e3ef" severity="AVOID" section="Coding" subsection="Fields">AVOID naming fields with camelCase.</guideline>
   <guideline key="Ch06_30a3139" severity="AVOID" section="Coding" subsection="Fields">AVOID constant fields for values that will change over time.</guideline>
   <guideline key="Ch06_8030561" severity="DO" section="Coding" subsection="Fields">DO use constant fields for values that will never change.</guideline>
-  <guideline key="" severity="DO" section="Coding" subsection="Fields">DO name fields with PascalCase and a leading underscore.</guideline>
+  <guideline severity="DO" section="Coding" subsection="Fields">DO name fields with PascalCase and a leading underscore.</guideline>
   <guideline key="Ch06_d80065c" severity="DO" section="Coding" subsection="Fields">DO declare all instance fields as private (and expose them via a property).</guideline>
   <guideline key="Ch06_389b3f9" severity="CONSIDER" section="Coding" subsection="Fields">CONSIDER initializing static fields inline rather than explicitly using static constructors or declaration assigned values.</guideline>
   <guideline key="Ch05_0d6dee5" severity="CONSIDER" section="Coding" subsection="Files">CONSIDER organizing the directory hierarchy for source code files to match the namespace hierarchy.</guideline>
@@ -246,6 +246,8 @@
   <guideline key="Ch14_6baa967" severity="DO" section="Coding" subsection="Types">DO use System.EventArgs or a type that derives from System.EventArgs for a TEventArgs type.</guideline>
   <guideline key="Ch03_f566c99" severity="AVOID" section="Coding" subsection="Types">AVOID using implicitly typed local variables unless the data type of the assigned value is obvious.</guideline>
   <guideline key="Ch14_3e1089d" severity="CONSIDER" section="Coding" subsection="Types">CONSIDER using System.EventHandler&lt;T&gt; instead of manually creating new delegate types for event handlers unless the parameter names of a custom type offer significant clarification.</guideline>
+  <guideline severity="CONSIDER" section="Coding" subsection="Variables">CONSIDER using var any time that the initialization of the variable clearly shows what the variable will contain.</guideline>
+  <guideline severity="CONSIDER" section="Coding" subsection="Variables">CONSIDER using target-typed new expressions any time that the instance clearly shows its type.</guideline>
   <guideline key="Ch04_9fa9f67" severity="AVOID" section="Coding" subsection="Whitespace">"AVOID omitting braces, except for the simplest of single-line if statements."</guideline>
   <guideline key="Ch04_19bd2d2" severity="DO" section="Coding" subsection="Whitespace">"DO use parentheses to make code more readable, particularly if the operator precedence is not clear to the casual reader."</guideline>
 </Guidelines>

docs/coding/csharp.md

@@ -30,6 +30,7 @@
      - [Threads](#threads)
      - [ToString()](#tostring)
      - [Types](#types)
+     - [Variables](#variables)
      - [Whitespace](#whitespace)
 
 # Guidelines
@@ -340,6 +341,10 @@
 - :no_entry: AVOID using implicitly typed local variables unless the data type of the assigned value is obvious.
 - :grey_question: CONSIDER using System.EventHandler<T> instead of manually creating new delegate types for event handlers unless the parameter names of a custom type offer significant clarification.
 
+### Variables
+- :grey_question: CONSIDER using var any time that the initialization of the variable clearly shows what the variable will contain.
+- :grey_question: CONSIDER using target-typed new expressions any time that the instance clearly shows its type.
+
 ### Whitespace
 - :no_entry: AVOID omitting braces, except for the simplest of single-line if statements.
 - :heavy_check_mark: DO use parentheses to make code more readable, particularly if the operator precedence is not clear to the casual reader.