Introduction

WPF XAML files use XML syntax, so comments follow the XML comment rules rather than a C# style line comment. The mechanism is simple, but the important detail is knowing where comments are valid and where they will break parsing.

Use XML Comment Syntax

In XAML, comments use the standard XML form <!-- comment -->. You can place them between elements, above controls, or around sections you want to temporarily disable while editing.

1<Window x:Class="CommentDemo.MainWindow"
2        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
3        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
4        Title="Comment Demo" Height="220" Width="320">
5    <Grid Margin="16">
6        <!-- Main heading shown at the top of the window -->
7        <TextBlock Text="Settings"
8                   FontSize="24"
9                   FontWeight="Bold" />
10
11        <!-- Future filter controls go in this area -->
12        <StackPanel Margin="0,48,0,0">
13            <CheckBox Content="Enable notifications" />
14            <CheckBox Content="Start on login" />
15        </StackPanel>
16    </Grid>
17</Window>

That is the normal, supported way to document structure in a XAML file.

Comment Out Existing Markup

Because comments can wrap whole XML fragments, they are useful when you want to temporarily remove a block from the visual tree during debugging.

1<Grid>
2    <TextBlock Text="Visible content" />
3
4    <!--
5    <Border Background="LightYellow" Padding="8" Margin="0,32,0,0">
6        <TextBlock Text="Temporarily disabled panel" />
7    </Border>
8    -->
9</Grid>

This works well for short experiments, especially while testing layout changes. It is still better to delete dead markup once you know the block is no longer needed.

Where Comments Are Not Allowed

XML comments are not valid everywhere. The two rules that matter most are:

• do not place a comment inside an attribute value
• do not nest one XML comment inside another

For example, this is invalid because the comment appears inside an attribute value:

<Button Content="Save <!-- invalid here -->" />

And this is invalid because XML comments cannot be nested:

<!-- outer comment
    <!-- inner comment -->
-->

If you need to annotate an attribute choice, put the comment on the line above the element instead.

Keep Comments Focused on Intent

The best comments explain why a block exists, not what the markup obviously says. A comment such as “button control” adds no information. A comment such as “kept in the tab order for keyboard accessibility” is useful because it explains intent.

This matters in XAML because the markup is already descriptive. Over-commenting makes the file harder to scan and encourages stale notes that no longer match the UI.

A practical guideline is to comment these cases:

• unusual layout workarounds
• interoperability with code-behind or custom controls
• accessibility or localization constraints
• temporary diagnostics that will be removed soon

Comments and the WPF Designer

The Visual Studio XAML designer generally ignores comments, which is what you want. They are for maintainers, not for runtime behavior. If a comment seems to affect parsing, the real issue is usually malformed XML around it rather than the comment itself.

When a XAML file stops loading in the designer after a comment edit, check for these problems first:

• an unclosed comment marker
• an illegal nested comment
• accidental removal of an element boundary near the comment

Those mistakes are easy to make when commenting out a large block.

A Small Realistic Example

The following example shows useful comments without cluttering the file.

1<UserControl x:Class="CommentDemo.SettingsPanel"
2             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
3             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
4    <Grid Margin="12">
5        <Grid.RowDefinitions>
6            <RowDefinition Height="Auto" />
7            <RowDefinition Height="Auto" />
8            <RowDefinition Height="*" />
9        </Grid.RowDefinitions>
10
11        <!-- Keep this text separate because localization can expand it substantially. -->
12        <TextBlock Grid.Row="0"
13                   Text="Account preferences"
14                   FontSize="20"
15                   FontWeight="SemiBold" />
16
17        <!-- The ComboBox is bound in code-behind because values come from a legacy API. -->
18        <ComboBox Grid.Row="1" Margin="0,12,0,0" />
19    </Grid>
20</UserControl>

The comments tell the next developer something the markup alone does not.

Common Pitfalls

A common mistake is using comments to hide large amounts of obsolete XAML for long periods. That turns the file into an archive instead of a source file. Remove code that is not coming back.

Another mistake is writing comments that restate the visible control names. If the comment is obvious, it should probably be deleted.

Developers also run into parser errors by forgetting that XML comments cannot be nested. When disabling a large section, inspect the block first for existing comments.

Finally, do not use comments to store TODO lists that belong in issue tracking. A short local note is fine, but long-lived work items age badly inside markup files.

Summary

• XAML comments use standard XML syntax: <!-- comment -->.
• Place comments between elements or around blocks, not inside attribute values.
• Do not nest XML comments.
• Use comments to explain intent, constraints, or temporary debugging context.
• Delete obsolete commented-out markup instead of keeping it indefinitely.