feat: Add MsTest analyzer to suggest DisplayName and Description attributes for commented tests

Documentation/Diagnostics/PH2150.md

@@ -0,0 +1,68 @@
+# PH2150: Test should use DisplayName or Description attribute instead of comments
+
+| Property | Value  |
+|--|--|
+| Package | [Philips.CodeAnalysis.MsTestAnalyzers](https://www.nuget.org/packages/Philips.CodeAnalysis.MsTestAnalyzers) |
+| Diagnostic ID | PH2150 |
+| Category  | [MsTest](../MsTest.md) |
+| Analyzer | [TestShouldUseDisplayNameAnalyzer](https://github.com/philips-software/roslyn-analyzers/blob/main/Philips.CodeAnalysis.MsTestAnalyzers/TestShouldUseDisplayNameAnalyzer.cs)
+| CodeFix  | No |
+| Severity | Info |
+| Enabled By Default | No |
+
+## Introduction
+
+Test methods and DataRow attributes often contain inline comments that describe their purpose, but these comments are not visible in test runners. MSTest provides better alternatives: `Description` attribute for test methods and `DisplayName` parameter for DataRow attributes.
+
+## How to solve
+
+For test methods with meaningful comments, add a `Description` attribute instead of using inline comments.
+
+For DataRow attributes with meaningful comments, add a `DisplayName` parameter instead of using inline comments.
+
+## Example
+
+Code that triggers a diagnostic:
+``` cs
+[TestClass]
+public class TestClass
+{
+    // This test verifies that addition works correctly
+    [TestMethod]
+    public void TestAddition() { }
+
+    [DataTestMethod]
+    [DataRow(1, 2)] // Should add positive numbers
+    [DataRow(-1, 1)] // Should handle negative numbers
+    public void TestAdditionWithData(int a, int b) { }
+}
+```
+
+And the replacement code:
+``` cs
+[TestClass]
+public class TestClass
+{
+    [TestMethod]
+    [Description("This test verifies that addition works correctly")]
+    public void TestAddition() { }
+
+    [DataTestMethod]
+    [DataRow(1, 2, DisplayName = "Should add positive numbers")]
+    [DataRow(-1, 1, DisplayName = "Should handle negative numbers")]
+    public void TestAdditionWithData(int a, int b) { }
+}
+```
+
+## Configuration
+
+This analyzer ignores certain boilerplate comment patterns to reduce noise:
+- Comments starting with `TODO`
+- Comments starting with `FIXME`
+- Comments starting with `HACK`
+- Comments starting with `NOTE`
+- Comments starting with `BUG`
+
+Additionally, comments with 5 or fewer characters are considered too short to be meaningful and are ignored.
+
+This analyzer does not offer any special configuration. The general ways of [suppressing](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/suppress-warnings) diagnostics apply.

Philips.CodeAnalysis.Common/DiagnosticId.cs

@@ -140,6 +140,7 @@ public enum DiagnosticId
 		AvoidToStringOnString = 2146,
 		AvoidVariableNamedUnderscore = 2147,
 		AvoidProblematicUsingPatterns = 2149,
+		UseDisplayNameOrDescription = 2150,
 		AvoidTodoComments = 2151,
 		AvoidUnusedToString = 2153,
 		AvoidUnlicensedPackages = 2155,

Philips.CodeAnalysis.MaintainabilityAnalyzers/Maintainability/AvoidStringFormatInInterpolatedStringAnalyzer.cs

@@ -1,4 +1,4 @@
-// © 2025 Koninklijke Philips N.V. See License.md in the project root for license information.
+// © 2025 Koninklijke Philips N.V. See License.md in the project root for license information.
 
 using Microsoft.CodeAnalysis;
 using Microsoft.CodeAnalysis.CSharp;

Philips.CodeAnalysis.MsTestAnalyzers/TestShouldUseDisplayNameAnalyzer.cs

@@ -0,0 +1,157 @@
+// © 2025 Koninklijke Philips N.V. See License.md in the project root for license information.
+
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.Linq;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+using Microsoft.CodeAnalysis.Diagnostics;
+using Philips.CodeAnalysis.Common;
+
+namespace Philips.CodeAnalysis.MsTestAnalyzers
+{
+	[DiagnosticAnalyzer(LanguageNames.CSharp)]
+	public class TestShouldUseDisplayNameAnalyzer : TestMethodDiagnosticAnalyzer
+	{
+		private const string Title = @"Test should use DisplayName or Description attribute instead of comments";
+		public const string MessageFormat = @"Consider using DisplayName parameter for DataRow or Description attribute for test method instead of inline comments";
+		private const string Description = @"Using DisplayName parameter for DataRow attributes or Description attribute for test methods makes test purpose more visible in test runners and provides better documentation.";
+		private const string Category = Categories.MsTest;
+
+		private static readonly DiagnosticDescriptor Rule = new(DiagnosticId.UseDisplayNameOrDescription.ToId(), Title, MessageFormat, Category, DiagnosticSeverity.Error, isEnabledByDefault: false, description: Description);
+
+		public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics => ImmutableArray.Create(Rule);
+
+		protected override TestMethodImplementation OnInitializeTestMethodAnalyzer(AnalyzerOptions options, Compilation compilation, MsTestAttributeDefinitions definitions)
+		{
+			return new TestShouldUseDisplayName(definitions, Helper);
+		}
+
+		public class TestShouldUseDisplayName : TestMethodImplementation
+		{
+			public TestShouldUseDisplayName(MsTestAttributeDefinitions definitions, Helper helper) : base(definitions, helper)
+			{ }
+
+			protected override void OnTestMethod(SyntaxNodeAnalysisContext context, MethodDeclarationSyntax methodDeclaration, IMethodSymbol methodSymbol, bool isDataTestMethod)
+			{
+				if (isDataTestMethod)
+				{
+					CheckDataTestMethodForDisplayName(context, methodDeclaration);
+				}
+				else
+				{
+					CheckTestMethodForDescription(context, methodDeclaration);
+				}
+			}
+
+			private void CheckDataTestMethodForDisplayName(SyntaxNodeAnalysisContext context, MethodDeclarationSyntax methodDeclaration)
+			{
+				// Check for DataRow attributes with comments but no DisplayName
+				IEnumerable<AttributeSyntax> dataRowAttributes = methodDeclaration.AttributeLists
+					.SelectMany(list => list.Attributes)
+					.Where(attr => Helper.ForAttributes.IsDataRowAttribute(attr, context));
+
+				foreach (AttributeSyntax attribute in dataRowAttributes)
+				{
+					// Check if this DataRow has a comment but no DisplayName
+					var hasDisplayName = attribute.ArgumentList?.Arguments.Any(arg =>
+						arg.NameEquals?.Name.Identifier.ValueText == "DisplayName") ?? false;
+
+					if (!hasDisplayName)
+					{
+						// Look for trailing comment on the same line
+						var comment = GetMeaningfulTrailingComment(attribute);
+						if (!string.IsNullOrWhiteSpace(comment))
+						{
+							var diagnostic = Diagnostic.Create(Rule, attribute.GetLocation());
+							context.ReportDiagnostic(diagnostic);
+						}
+					}
+				}
+			}
+
+			private void CheckTestMethodForDescription(SyntaxNodeAnalysisContext context, MethodDeclarationSyntax methodDeclaration)
+			{
+				// Check if test method has Description attribute
+				var hasDescription = Helper.ForAttributes.HasAttribute(methodDeclaration.AttributeLists, context, MsTestFrameworkDefinitions.DescriptionAttribute, out _, out _);
+
+				if (!hasDescription)
+				{
+					// Look for leading comment before the method
+					var comment = GetMeaningfulLeadingComment(methodDeclaration);
+					if (!string.IsNullOrWhiteSpace(comment))
+					{
+						var diagnostic = Diagnostic.Create(Rule, methodDeclaration.Identifier.GetLocation());
+						context.ReportDiagnostic(diagnostic);
+					}
+				}
+			}
+
+			private string GetMeaningfulTrailingComment(AttributeSyntax attribute)
+			{
+				// Look for the parent AttributeListSyntax to get the closing bracket
+				if (attribute.Parent is AttributeListSyntax attributeList)
+				{
+					SyntaxToken closeBracketToken = attributeList.CloseBracketToken;
+					SyntaxTrivia trivia = closeBracketToken.TrailingTrivia.FirstOrDefault(t => t.IsKind(SyntaxKind.SingleLineCommentTrivia));
+
+					if (trivia.IsKind(SyntaxKind.SingleLineCommentTrivia))
+					{
+						return ExtractCommentText(trivia.ToString());
+					}
+				}
+
+				return string.Empty;
+			}
+
+			private string GetMeaningfulLeadingComment(MethodDeclarationSyntax methodDeclaration)
+			{
+				SyntaxTriviaList leadingTrivia = methodDeclaration.GetLeadingTrivia();
+
+				// Look for single-line comment immediately before the method
+				SyntaxTrivia comment = leadingTrivia.LastOrDefault(t => t.IsKind(SyntaxKind.SingleLineCommentTrivia));
+				if (comment.IsKind(SyntaxKind.SingleLineCommentTrivia))
+				{
+					return ExtractCommentText(comment.ToString());
+				}
+
+				return string.Empty;
+			}
+
+			private string ExtractCommentText(string commentTrivia)
+			{
+				if (string.IsNullOrWhiteSpace(commentTrivia))
+				{
+					return string.Empty;
+				}
+
+				// Remove // and trim whitespace
+				var text = commentTrivia.Trim();
+				if (text.StartsWith("//"))
+				{
+					text = text.Substring(2).Trim();
+				}
+
+				// Only consider meaningful comments (more than just a few characters)
+				if (text.Length <= 5)
+				{
+					return string.Empty;
+				}
+
+				// Filter out boilerplate comment patterns
+				var upperText = text.ToUpperInvariant();
+				if (upperText.StartsWith("TODO") ||
+					upperText.StartsWith("FIXME") ||
+					upperText.StartsWith("HACK") ||
+					upperText.StartsWith("NOTE") ||
+					upperText.StartsWith("BUG"))
+				{
+					return string.Empty;
+				}
+
+				return text;
+			}
+		}
+	}
+}