trainer-demo-deploy: Instructions file for GitHub Copilot

Self-explanatory Code Commenting Instructions

Language-Specific Precedence

Language-specific instruction files take precedence over these general guidelines. In particular:

• C# / .NET (az-dotnet-webapp.instructions.md if present): use XML doc comments (/// <summary>) on all public types and members.
• PowerShell (az-powershell.instructions.md): always include comment-based help (.SYNOPSIS, .DESCRIPTION, .EXAMPLE) on public functions.
• Bicep (az-bicep-code-best-practices.instructions.md): always use @description annotations on parameters, variables, and outputs.
• Shell (shell.instructions.md): include a header comment explaining the script's purpose.

These requirements are additive — public-facing APIs and parameters must be documented per their language rules, while internal code follows the minimal-comment philosophy below.

Core Principle

Write code that speaks for itself. Comment only when necessary to explain WHY, not WHAT. We do not need comments most of the time.

Commenting Guidelines

❌ AVOID These Comment Types

Obvious Comments

// Bad: States the obvious
int counter = 0;  // Initialize counter to zero
counter++;  // Increment counter by one

Redundant Comments

// Bad: Comment repeats the code
public string GetUserName()
{
    return user.Name;  // Return the user's name
}

Outdated Comments

// Bad: Comment doesn't match the code
// Calculate tax at 5% rate
var tax = price * 0.08m;  // Actually 8%

✅ WRITE These Comment Types

Complex Business Logic

// Good: Explains WHY this specific calculation
// Apply progressive tax brackets: 10% up to 10k, 20% above
var tax = CalculateProgressiveTax(income, [0.10m, 0.20m], [10000m]);

Non-obvious Algorithms

// Good: Explains the algorithm choice
// Using Floyd-Warshall for all-pairs shortest paths
// because we need distances between all nodes
for (int k = 0; k < vertices; k++)
{
    for (int i = 0; i < vertices; i++)
    {
        for (int j = 0; j < vertices; j++)
        {
            // ... implementation
        }
    }
}