diff --git a/.github/workflows/ConvertGuidelinesXmlToMarkdown.yml b/.github/workflows/ConvertGuidelinesXmlToMarkdown.yml index 6fbb675b..f82ca683 100644 --- a/.github/workflows/ConvertGuidelinesXmlToMarkdown.yml +++ b/.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' }} diff --git a/.github/workflows/manuallyRunXmlToMD.yml b/.github/workflows/manuallyRunXmlToMD.yml index 40708c81..a5b935b1 100644 --- a/.github/workflows/manuallyRunXmlToMD.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index 106e8301..46588e45 100644 --- a/.gitignore +++ b/.gitignore @@ -349,4 +349,5 @@ healthchecksdb MigrationBackup/ .idea -.DS_Store \ No newline at end of file +.DS_Store +.devcontainer \ No newline at end of file diff --git a/Tools/XMLtoMD/GuidelineXmlToMD.Test/Data/TestGuidelines.xml b/Tools/XMLtoMD/GuidelineXmlToMD.Test/Data/TestGuidelines.xml new file mode 100644 index 00000000..a634680a --- /dev/null +++ b/Tools/XMLtoMD/GuidelineXmlToMD.Test/Data/TestGuidelines.xml @@ -0,0 +1,4 @@ + + + My name is Inigo Montoya. + diff --git a/Tools/XMLtoMD/GuidelineXmlToMD.Test/GuidelineXmlFileReaderTest.cs b/Tools/XMLtoMD/GuidelineXmlToMD.Test/GuidelineXmlFileReaderTest.cs new file mode 100644 index 00000000..f198557f --- /dev/null +++ b/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 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); + + } + } +} diff --git a/Tools/XMLtoMD/GuidelineXmlToMD.Test/GuidelineXmlToMD.Test.csproj b/Tools/XMLtoMD/GuidelineXmlToMD.Test/GuidelineXmlToMD.Test.csproj new file mode 100644 index 00000000..7c90c485 --- /dev/null +++ b/Tools/XMLtoMD/GuidelineXmlToMD.Test/GuidelineXmlToMD.Test.csproj @@ -0,0 +1,20 @@ + + + + net5.0 + CA2007,CA1815,CA1303,CA1707,CA1305,IDE0008,INTL0003 + false + + + + + + + + + + + + + + diff --git a/XMLtoMD/GuidelineXmlToMD/GuidelineXmlToMD.sln b/Tools/XMLtoMD/GuidelineXmlToMD.sln similarity index 55% rename from XMLtoMD/GuidelineXmlToMD/GuidelineXmlToMD.sln rename to Tools/XMLtoMD/GuidelineXmlToMD.sln index 3a790ba9..6a6064ca 100644 --- a/XMLtoMD/GuidelineXmlToMD/GuidelineXmlToMD.sln +++ b/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 diff --git a/XMLtoMD/GuidelineXmlToMD/.config/dotnet-tools.json b/Tools/XMLtoMD/GuidelineXmlToMD/.config/dotnet-tools.json similarity index 100% rename from XMLtoMD/GuidelineXmlToMD/.config/dotnet-tools.json rename to Tools/XMLtoMD/GuidelineXmlToMD/.config/dotnet-tools.json diff --git a/XMLtoMD/GuidelineXmlToMD/GlobalSuppressions.cs b/Tools/XMLtoMD/GuidelineXmlToMD/GlobalSuppressions.cs similarity index 100% rename from XMLtoMD/GuidelineXmlToMD/GlobalSuppressions.cs rename to Tools/XMLtoMD/GuidelineXmlToMD/GlobalSuppressions.cs diff --git a/Tools/XMLtoMD/GuidelineXmlToMD/Guideline.cs b/Tools/XMLtoMD/GuidelineXmlToMD/Guideline.cs new file mode 100644 index 00000000..2df0f60c --- /dev/null +++ b/Tools/XMLtoMD/GuidelineXmlToMD/Guideline.cs @@ -0,0 +1,4 @@ +namespace GuidelineXmlToMD +{ + public record Guideline(string Key, string Text, string Severity, string Section, string Subsection) { }; +} diff --git a/Tools/XMLtoMD/GuidelineXmlToMD/GuidelineXmlFileReader.cs b/Tools/XMLtoMD/GuidelineXmlToMD/GuidelineXmlFileReader.cs new file mode 100644 index 00000000..43bb01b8 --- /dev/null +++ b/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 ReadExisitingGuidelinesFile(string pathToExistingGuidelinesXml) + { + + XDocument previousGuidelines = XDocument.Load(pathToExistingGuidelinesXml); + + HashSet guidelines = new HashSet(); + + foreach (XElement guidelineFromXml in previousGuidelines.Root.DescendantNodes().OfType()) + { + 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; + } + + } +} diff --git a/XMLtoMD/GuidelineXmlToMD/GuidelineXmlToMD.csproj b/Tools/XMLtoMD/GuidelineXmlToMD/GuidelineXmlToMD.csproj similarity index 100% rename from XMLtoMD/GuidelineXmlToMD/GuidelineXmlToMD.csproj rename to Tools/XMLtoMD/GuidelineXmlToMD/GuidelineXmlToMD.csproj diff --git a/XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdExtensions.cs b/Tools/XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdExtensions.cs similarity index 100% rename from XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdExtensions.cs rename to Tools/XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdExtensions.cs diff --git a/XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdFormat.cs b/Tools/XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdFormat.cs similarity index 100% rename from XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdFormat.cs rename to Tools/XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdFormat.cs diff --git a/XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdStyle.cs b/Tools/XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdStyle.cs similarity index 100% rename from XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdStyle.cs rename to Tools/XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdStyle.cs diff --git a/XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdText.cs b/Tools/XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdText.cs similarity index 100% rename from XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdText.cs rename to Tools/XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdText.cs diff --git a/XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdWriter.cs b/Tools/XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdWriter.cs similarity index 100% rename from XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdWriter.cs rename to Tools/XMLtoMD/GuidelineXmlToMD/MarkdownOut/MdWriter.cs diff --git a/XMLtoMD/GuidelineXmlToMD/Program.cs b/Tools/XMLtoMD/GuidelineXmlToMD/Program.cs similarity index 100% rename from XMLtoMD/GuidelineXmlToMD/Program.cs rename to Tools/XMLtoMD/GuidelineXmlToMD/Program.cs diff --git a/XMLtoMD/GuidelineXmlToMD/Properties/launchSettings.json b/Tools/XMLtoMD/GuidelineXmlToMD/Properties/launchSettings.json similarity index 56% rename from XMLtoMD/GuidelineXmlToMD/Properties/launchSettings.json rename to Tools/XMLtoMD/GuidelineXmlToMD/Properties/launchSettings.json index 981c4922..59014ef1 100644 --- a/XMLtoMD/GuidelineXmlToMD/Properties/launchSettings.json +++ b/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\"" } } } \ No newline at end of file diff --git a/XMLtoMD/GuidelineXmlToMD/Guideline.cs b/XMLtoMD/GuidelineXmlToMD/Guideline.cs deleted file mode 100644 index 680b4285..00000000 --- a/XMLtoMD/GuidelineXmlToMD/Guideline.cs +++ /dev/null @@ -1,32 +0,0 @@ -using System.Collections.Generic; - - -namespace GuidelineXmlToMD -{ - public class Guideline - { - public string Key { get; set; } = ""; - public string Text { get; set; } = ""; - - public string Severity { get; set; } = ""; - - public string Section { get; set; } = ""; - public string Subsection { get; set; } = ""; - - public List Comments { get;} = new List(); - - public override int GetHashCode() - { - return Key.GetHashCode(); - } - - public override bool Equals(object obj) - { - Guideline otherGuideline = obj as Guideline; - - return otherGuideline != null && string.Equals(otherGuideline.Key, this.Key); - } - - } - -} diff --git a/XMLtoMD/GuidelineXmlToMD/GuidelineXmlFileReader.cs b/XMLtoMD/GuidelineXmlToMD/GuidelineXmlFileReader.cs deleted file mode 100644 index a92e6bea..00000000 --- a/XMLtoMD/GuidelineXmlToMD/GuidelineXmlFileReader.cs +++ /dev/null @@ -1,42 +0,0 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using System.Xml.Linq; - -namespace GuidelineXmlToMD -{ - static class GuidelineXmlFileReader - { - public const string _Guideline = "guideline"; - public const string _Key = "key"; - public const string _Severity = "severity"; - - public const string _Section = "section"; - public const string _Subsection = "subsection"; - public const string _Comments = "comments"; - - - public static ICollection ReadExisitingGuidelinesFile(string pathToExistingGuidelinesXml) - { - - XDocument previousGuidelines = XDocument.Load(pathToExistingGuidelinesXml); - - HashSet guidelines = new HashSet(); - - foreach (XElement guidelineFromXml in previousGuidelines.Root.DescendantNodes().OfType()) - { - Guideline guideline = new Guideline(); - guideline.Severity = guidelineFromXml.Attribute(_Severity)?.Value; - guideline.Subsection = guidelineFromXml.Attribute(_Subsection)?.Value; - guideline.Section = guidelineFromXml.Attribute(_Section)?.Value; - guideline.Text = guidelineFromXml?.Value; - guideline.Key = guidelineFromXml.Attribute(_Key)?.Value; - - guidelines.Add(guideline); - } - return guidelines; - } - - } -} diff --git a/docs/Guidelines(8th Edition).xml b/docs/Guidelines(8th Edition).xml index 80dc9759..a18f1b5d 100644 --- a/docs/Guidelines(8th Edition).xml +++ b/docs/Guidelines(8th Edition).xml @@ -99,7 +99,7 @@ AVOID naming fields with camelCase. AVOID constant fields for values that will change over time. DO use constant fields for values that will never change. - DO name fields with PascalCase and a leading underscore. + DO name fields with PascalCase and a leading underscore. DO declare all instance fields as private (and expose them via a property). CONSIDER initializing static fields inline rather than explicitly using static constructors or declaration assigned values. CONSIDER organizing the directory hierarchy for source code files to match the namespace hierarchy. @@ -246,6 +246,8 @@ DO use System.EventArgs or a type that derives from System.EventArgs for a TEventArgs type. AVOID using implicitly typed local variables unless the data type of the assigned value is obvious. 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. + CONSIDER using var any time that the initialization of the variable clearly shows what the variable will contain. + CONSIDER using target-typed new expressions any time that the instance clearly shows its type. "AVOID omitting braces, except for the simplest of single-line if statements." "DO use parentheses to make code more readable, particularly if the operator precedence is not clear to the casual reader." \ No newline at end of file diff --git a/docs/coding/csharp.md b/docs/coding/csharp.md index fd5ac16f..552be52a 100644 --- a/docs/coding/csharp.md +++ b/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 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.