XSLT - Creating Comments in Output with <xsl:comment> in XSLT

The <xsl:comment> element in XSLT is used to create XML or HTML comments in the output document. A comment is text that is included in the generated document for human readers but is ignored by XML or HTML processors. Comments are commonly used to provide explanations, mark sections, or make the generated output easier to understand and maintain. The <xsl:comment> instruction allows an XSLT stylesheet to generate these comments dynamically while transforming an XML document.

The basic syntax of <xsl:comment> is:

<xsl:comment>
    Comment text
</xsl:comment>

For example, suppose the input XML contains information about a student:

<student>
    <name>Rahul</name>
    <course>Computer Science</course>
</student>

An XSLT stylesheet can generate an HTML or XML comment using:

<xsl:template match="/">
    <student>
        <xsl:comment>
            Student information generated by XSLT
        </xsl:comment>

        <name>
            <xsl:value-of select="student/name"/>
        </name>

        <course>
            <xsl:value-of select="student/course"/>
        </course>
    </student>
</xsl:template>

The resulting output can be:

<student>
    <!--Student information generated by XSLT-->
    <name>Rahul</name>
    <course>Computer Science</course>
</student>

Here, <xsl:comment> tells the XSLT processor to create an actual comment in the result rather than treating the text as ordinary output. The generated comment does not affect the meaning of the surrounding XML elements. It is mainly intended for documentation and human readability.

Creating Dynamic Comments

One important advantage of <xsl:comment> is that the comment content can be generated dynamically from the source XML. This is useful when the comment needs to contain information that changes for every record.

Consider this XML:

<student>
    <name>Priya</name>
    <rollno>105</rollno>
</student>

The stylesheet can generate a comment containing the student's name:

<xsl:template match="/">
    <student>
        <xsl:comment>
            Processing record for
            <xsl:value-of select="student/name"/>
        </xsl:comment>

        <name>
            <xsl:value-of select="student/name"/>
        </name>
    </student>
</xsl:template>

The output will be similar to:

<student>
    <!--Processing record for Priya-->
    <name>Priya</name>
</student>

In this example, <xsl:value-of> retrieves the student's name from the source document, and <xsl:comment> places that value inside a generated comment.

Using <xsl:comment> with Templates

Comments can also be generated inside templates that process individual elements. For example:

<xsl:template match="student">
    <xsl:comment>
        Student record begins
    </xsl:comment>

    <student>
        <xsl:value-of select="name"/>
    </student>
</xsl:template>

If multiple student elements are processed, the XSLT processor can generate a corresponding comment for each processed record. This can be helpful when inspecting a large generated XML or HTML document.

Important Rules

The content generated by <xsl:comment> must follow the rules for comments in the output format. In XML, a comment cannot contain the sequence -- and cannot end with a hyphen. Therefore, the comment text should be constructed carefully when its contents are generated dynamically.

For example, this is invalid XML comment content:

<xsl:comment>
    Student -- Details
</xsl:comment>

because XML comments cannot contain consecutive hyphens.

A safer comment would be:

<xsl:comment>
    Student Details
</xsl:comment>

Difference Between <xsl:comment> and Ordinary Text

It is important to distinguish <xsl:comment> from normal text output.

For example:

<xsl:text>This is a note</xsl:text>

produces ordinary text:

This is a note

whereas:

<xsl:comment>This is a note</xsl:comment>

produces:

<!--This is a note-->

Thus, <xsl:text> creates text content, while <xsl:comment> creates a comment node in the result tree.

Practical Applications

<xsl:comment> can be useful when generating large XML or HTML documents where developers need additional information about how particular sections were produced. For example, an XSLT transformation could insert comments identifying the source record, processing stage, generated section, or transformation version.

For example:

<xsl:comment>
    Generated from customer record
</xsl:comment>

The resulting document might contain:

<!--Generated from customer record-->
<customer>
    ...
</customer>

These comments do not normally change how the document is processed, but they can make the generated output easier to inspect and debug.

Conclusion

The <xsl:comment> instruction provides a straightforward way to generate comments during an XSLT transformation. It can create fixed comments as well as comments containing dynamically generated information from the source XML. Because comments are separate from the actual data and structure of the result document, they are particularly useful for documentation, debugging, identifying generated sections, and improving the readability of transformed XML or HTML output.